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

本文介绍了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命令即可

1
2
3

curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者wget（效果一样）
wget -qO- https://astral.sh/uv/install.sh | sh

在windows上的安装命令如下

1	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命令确认安装成功。

1 2	❯ uv --version uv 0.6.14 (a4cec56dc 2025-04-09)

2.1. 卸载uv

卸载uv之前，先执行如下命令删除所有本地缓存文件

1
2
3

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版本（包括已经安装的和可以安装的）

1	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                 <download available>
cpython-3.14.0a6+freethreaded-macos-aarch64-none    <download available>
cpython-3.13.3-macos-aarch64-none                   <download available>
cpython-3.13.3+freethreaded-macos-aarch64-none      <download available>
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                  <download available>
cpython-3.11.12-macos-aarch64-none                  <download available>
cpython-3.10.17-macos-aarch64-none                  <download available>
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                   <download available>
cpython-3.9.6-macos-aarch64-none                    /usr/bin/python3
cpython-3.8.20-macos-aarch64-none                   <download available>

如果需要安装其他版本的python，使用如下命令

1	uv python install 3.12

除了标准python之外，还可以安装其他的Python实现，比如PyPy实现的python

1	uv python install pypy@3.10

查找某个python版本的路径

1 2	❯ uv python find 3.10 /Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10

查看已经安装的python版本

1	uv python list

3.2. 选用python版本

在具体的某个项目中，进入项目目录，使用如下命令指定选用的python版本

1	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虚拟环境

1 2	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之后添加一个项目名，会自动创建项目文件夹

1	uv init 项目名

如果需要指定特定python版本，建议使用第一种方式来创建项目，否则还需要手动修改pyproject.toml配置文件里面需要的python版本。

3.4. 添加依赖

1	uv add 依赖项

比如添加requests库

1	uv add requests

还可以指定具体版本

1	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程序了

1	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. 大模型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都没有的尴尬情况了。