【Python】使用uv管理python虚拟环境

06-01 1163阅读

本文介绍了python虚拟环境管理工具uv，包括uv的作用、uv的常用命令等等。

参考：UV - 管理Python 版本、环境、第三方包

1. 介绍uv

官网：https://docs.astral.sh/uv/

uv是一个python虚拟环境管理工具，可以用来替代pip、pyenv、virtualenv等等工具。根据官网的介绍，使用uv来管理虚拟环境，相比于pip能得到至少10倍以上的性能提升。

uv工具有如下功能：

管理python版本；
管理第三方库（Python packages）的版本；
拥有全局的第三方库的缓存，能减少磁盘空间占用；
安装uv不需要python环境，可以通过curl或pip安装；
多平台支持：macOS、Linux、Windows;
试用过后，感觉uv还是很不错的，于是编写本文，推荐给大家。

2. 安装uv

文档：https://docs.astral.sh/uv/getting-started/installation/

在linux和mac上的安装直接使用curl或者wget命令即可
```
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者wget（效果一样）
wget -qO- https://astral.sh/uv/install.sh | sh
```
在windows上的安装命令如下
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
在mac上安装之后，终端输出如下
```
❯ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.6.14 aarch64-apple-darwin
no checksums to verify
installing to /Users/mothra/.local/bin
  uv
  uvx
everything's installed!
To add $HOME/.local/bin to your PATH, either restart your shell or run:
    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)
```
这里给出了提示，必须把$HOME/.local/bin这个路径加到环境变量PATH里面才可以正常使用uv工具。设置之后，使用uv --version命令确认安装成功。
```
❯ uv --version
uv 0.6.14 (a4cec56dc 2025-04-09)
```
2.1. 卸载uv

卸载uv之前，先执行如下命令删除所有本地缓存文件
```
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
```
然后再删除uv的二进制文件
```
# mac/linux
rm ~/.local/bin/uv ~/.local/bin/uvx
# windows
rm $HOME.local\bin\uv.exe
rm $HOME.local\bin\uvx.exe
```
3. 基本使用

3.1. 管理python版本

使用如下命令，显示出当前环境中所有可用的python版本（包括已经安装的和可以安装的）
```
uv python list
```
在我的电脑上，输出如下，我的电脑上安装了python 3.9.6（xcode开发者工具安装的）、python 3.10.11、python 3.13.1版本，这几个版本都可以用uv来调用。
```
❯ uv python list
cpython-3.14.0a6-macos-aarch64-none                 
cpython-3.14.0a6+freethreaded-macos-aarch64-none    
cpython-3.13.3-macos-aarch64-none                   
cpython-3.13.3+freethreaded-macos-aarch64-none      
cpython-3.13.1-macos-aarch64-none                   /opt/homebrew/bin/python3.13 -> ../Cellar/python@3.13/3.13.1/bin/python3.13
cpython-3.13.1-macos-aarch64-none                   /opt/homebrew/bin/python3 -> ../Cellar/python@3.13/3.13.1/bin/python3
cpython-3.13.0a3-macos-aarch64-none                 /usr/local/bin/python3.13 -> ../../../Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.12.10-macos-aarch64-none                  
cpython-3.11.12-macos-aarch64-none                  
cpython-3.10.17-macos-aarch64-none                  
cpython-3.10.11-macos-aarch64-none                  /usr/local/bin/python3.10 -> ../../../Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.10.11-macos-aarch64-none                  /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.10/bin/python3
cpython-3.10.11-macos-aarch64-none                  /Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.10.11-macos-aarch64-none                  /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 -> python3.10
cpython-3.9.22-macos-aarch64-none                   
cpython-3.9.6-macos-aarch64-none                    /usr/bin/python3
cpython-3.8.20-macos-aarch64-none                   
```
如果需要安装其他版本的python，使用如下命令
```
uv python install 3.12
```
除了标准python之外，还可以安装其他的Python实现，比如PyPy实现的python
```
uv python install pypy@3.10
```
查找某个python版本的路径
```
❯ uv python find 3.10
/Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10
```
查看已经安装的python版本
```
uv python list
```
3.2. 选用python版本

在具体的某个项目中，进入项目目录，使用如下命令指定选用的python版本
```
uv python pin 版本号
```
这个命令会在指定目录下创建一个.python-version文件，内容如下
```
❯ uv python pin 3.10                                    
Pinned `.python-version` to `3.10`
❯ cat .python-version  
3.10
```
注意，这里选用的python版本只和uv管理的虚拟环境有关系，和我们全局的python、python3命令都没有关系。

3.3. 创建虚拟环境（项目）

创建项目有两种方式，第一种方式，先创建好项目目录，然后设置python版本并初始化uv虚拟环境
```
uv python pin 3.10
uv init # 初始化
```
执行了uv init之后，会在当前目录下创建几个文件，同时也会在当前目录下执行git init创建出一个新的git仓库来
```
~/data/code/python/test_code        
❯ uv python pin 3.13
Pinned `.python-version` to `3.13`
~/data/code/python/test_code        
❯ uv init           
Initialized project `test-code`
~/data/code/python/test_code main ?6
❯ ls
README.md      main.py        pyproject.toml
```
另外一个方式是在init之后添加一个项目名，会自动创建项目文件夹
```
uv init 项目名
```
如果需要指定特定python版本，建议使用第一种方式来创建项目，否则还需要手动修改pyproject.toml配置文件里面需要的python版本。

3.4. 添加依赖
```
uv add 依赖项
```
比如添加requests库
```
uv add requests
```
还可以指定具体版本
```
uv add requests==版本号
```
执行了这个命令后，会在当前目录下创建.venv虚拟环境目录（在vscode里面可以选择这个目录作为虚拟环境，否则代码解析会有问题），并添加我们要的依赖项，同时会新增一个uv.lock文件，用于存放依赖项版本相关的信息。pyproject.toml文件中的dependencies字段也会包含需要的依赖项。
```
~/data/code/python/test_code main ?6
❯ uv add requests
Using CPython 3.13.1 interpreter at: /opt/homebrew/opt/python@3.13/bin/python3.13
Creating virtual environment at: .venv
Resolved 6 packages in 13.85s
Prepared 5 packages in 5.55s
Installed 5 packages in 13ms
 + certifi==2025.1.31
 + charset-normalizer==3.4.1
 + idna==3.10
 + requests==2.32.3
 + urllib3==2.4.0
```
而且，从这个输出中也能看到，它自动使用了.python-version指定的3.13版本的python，和当前我们全局目录下的python3指向什么版本没有关系（我的全局python3指向的是3.10版本）

3.5. 运行程序

依赖添加好后，就可以使用uv来运行python程序了
```
uv run 程序文件名 [命令行参数]
```
uv会自动按照我们的配置来运行程序，无序我们手动维护依赖项，也不需要手动去source各式各样的虚拟环境了。

3.6. uvx命令

随着uv下载的还有一个uvx命令，uvx命令本质上是uv tool run命令的别名，
```
uvx python main.py
# 等价于
uv run main.py
# 等价于
uv tool run main.py
```
实际例子，如下这两个命令是等价的
```
❯ uvx --directory ~/data/code/python/test_code python main.py
Hello from test-code!
    
❯ uv tool run --directory ~/data/code/python/test_code python main.py
Hello from test-code!
```
3.7. 小结

基本操作就是这些了，更多复杂的操作详见uv的官网。

4. 设置下载包的镜像源

参考：https://blog.csdn.net/qq_41472205/article/details/145686414

uv下载第三方库本质上也是通过pypi源下载的，所以在国内网络环境中默认链接速度会很慢，可以在项目目录的pyproject.toml中添加如下内容来使用清华源
```
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
```
运行uv add命令的时候也可以指定镜像源
```
uv add --default-index https://pypi.tuna.tsinghua.edu.cn/simple requests
```
uv也提供了全局的配置项，可以通过环境变量UV_DEFAULT_INDEX配置镜像源
```
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
```
全局的配置项优先级低于pyproject.toml中配置的镜像源。如果pyproject.toml里面配置了镜像源，则会使用pyproject.toml的配置。

5. 大模型mcp协议和uv

最近，ai agent中mcp协议的推出，让慕雪了解到了uv工具。对于mcp而言，mcp server的开发可以使用python来编写，此时python环境的管理就非常重要了。

以常见的mcp客户端配置举例，示例配置如下，其中test.py是我们编写的一个mcp服务器。
```
{
	"mcpServers": {
		"工具名称": {
			"command": "uv",
			"args": {
				"--directory",
				"工作路径",
				"run",
				"test.py"
			}
		}
	}
}
```
下图是mcp server和mcp client交互的简要逻辑（这只是个简要的流程）
```
graph TD;
	A[ai工具加载mcp配置] --> |启动mcp服务器|B
	B[mcp client] --> |链接服务器，调用工具|C[mcp server] 
	C -->|返回工具调用结果|B
```
其中第一步，ai工具加载mcp配置的时候，就需要去根据我们填写的mcpSever的配置来通过uv启动我们的服务端了，此时如果还是用python自带的venv来管理虚拟环境就不够用了，因为这里没有办法指定虚拟环境的路径，也没有人去source venv/bin/activate那个虚拟环境，所以mcp需要一个解决方案来更好的管理python的虚拟环境，此时uv就登场了。

使用了uv，直接执行uv run就可以了，uv工具自动帮我们维护了虚拟环境，并使用了指定环境来运行我们的服务端代码，一切问题都解决啦！

而且，mcp强制使用uv，也进一步规范了使用python编写mcp server的格式，再也不用担心某些开源python项目的根目录下连requirements.txt都没有的尴尬情况了。

本文首发地址：【Python】使用uv管理python虚拟环境，首发于 2025-04-14 21:29:43

点我查看更多精彩内容：慕雪的寒舍

免责声明：我们致力于保护作者版权，注重分享，被刊用文章因无法核实真实出处，未能及时与作者取得联系，或有版权异议的，请联系管理员，我们会立即处理! 部分文章是来自自研大数据AI进行生成,内容摘自(百度百科,百度知道,头条百科,中国民法典,刑法,牛津词典,新华词典,汉语词典,国家院校,科普平台)等数据,内容仅供学习参考,不准确地方联系删除处理! 图片声明：本站部分配图来自人工智能系统AI生成,觅知网授权图片,PxHere摄影无版权图库和百度，360，搜狗等多加搜索引擎自动关键词搜索配图，如有侵权的图片，请第一时间联系我们。

高速稳定云服务器9.9元起