Python包管理工具uv简单使用

uv用于管理python虚拟环境管理和依赖管理的一款新型工具，官方提示10-100x faster than pip。官方文档：https://docs.astral.sh/uv/

1. 下载uv

# macOS和Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# window
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# pip（网络不好情况下）
pip install uv

2. uv管理python

查看可用的 Python 版本：

(base) pywcc@wcc:~$ uv python list
cpython-3.14.0a6-linux-x86_64-gnu                 <download available>
cpython-3.14.0a6+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.13.2-linux-x86_64-gnu                   <download available>
cpython-3.13.2+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.12.9-linux-x86_64-gnu                   <download available>
cpython-3.12.3-linux-x86_64-gnu                   /bin/python3.12
cpython-3.12.3-linux-x86_64-gnu                   /bin/python3 -> python3.12
cpython-3.11.11-linux-x86_64-gnu                  <download available>
cpython-3.10.16-linux-x86_64-gnu                  <download available>
cpython-3.9.21-linux-x86_64-gnu                   miniconda3/bin/python3.9
cpython-3.9.21-linux-x86_64-gnu                   miniconda3/bin/python3 -> python3.9
cpython-3.9.21-linux-x86_64-gnu                   miniconda3/bin/python -> python3.9
cpython-3.9.21-linux-x86_64-gnu                   <download available>
cpython-3.8.20-linux-x86_64-gnu                   <download available>
cpython-3.7.9-linux-x86_64-gnu                    <download available>

查看已安装python路径：

# 查看当前python可执行文件路径(没有全部列出conda虚拟环境中的其他python)
uv python find

# 查看指定版本python可执行文件路径
uv python find 3.12

安装指定版本python：

#  vi ~/.bashrc（选择）
export UV_PYTHON_INSTALL_MIRROR=https://github.com/indygreg/python-build-standalone/releases/download

# 安装指定版本python
uv python install 3.14

# 删除指定版本pyrhon
uv python uninstall 3.14

3. uv创建虚拟环境

注意：使用conda环境pip安装uv，并使用uv创建虚拟环境需要退出conda环境，安装时使用新虚拟环境自带uv。否则使用uv sync不会更新pyproject.toml

# 指定环境路径和python版本
(base) pywcc@wcc:~$ uv venv python_venv/ -p 3.14
Using CPython 3.14.0a6
Creating virtual environment at: python_venv/
Activate with: source python_venv/bin/activate

# 激活python虚拟环境
source python_venv/bin/activate

# 退出虚拟环境
deactivate

4. uv管理项目

# 固定项目使用特定版本python
uv python pin 3.14

# 创建项目（先固定python版本，否则pyproject.toml取当前环境python版本）
uv init 项目目录名

(base) pywcc@wcc:~/test_uv$ ll
total 28
drwxrwxr-x  3 pywcc pywcc 4096 Apr  8 22:44 ./
drwxr-x--- 20 pywcc pywcc 4096 Apr  8 22:44 ../
drwxrwxr-x  7 pywcc pywcc 4096 Apr  8 22:44 .git/
-rw-rw-r--  1 pywcc pywcc  109 Apr  8 22:44 .gitignore
-rw-rw-r--  1 pywcc pywcc    4 Apr  8 22:44 .python-version
-rw-rw-r--  1 pywcc pywcc    0 Apr  8 22:44 README.md
-rw-rw-r--  1 pywcc pywcc   85 Apr  8 22:44 main.py
-rw-rw-r--  1 pywcc pywcc  152 Apr  8 22:44 pyproject.toml

# 同步项目pyproject.toml中python版本和依赖版本(会在当前目录创建.venv目录和uv.lock)
uv sync

(python_venv) (base) pywcc@wcc:~/test_uv$ ll
total 36
drwxrwxr-x  4 pywcc pywcc 4096 Apr  8 22:51 ./
drwxr-x--- 20 pywcc pywcc 4096 Apr  8 22:46 ../
drwxrwxr-x  7 pywcc pywcc 4096 Apr  8 22:44 .git/
-rw-rw-r--  1 pywcc pywcc  109 Apr  8 22:44 .gitignore
-rw-rw-r--  1 pywcc pywcc    4 Apr  8 22:44 .python-version
drwxrwxr-x  4 pywcc pywcc 4096 Apr  8 22:51 .venv/
-rw-rw-r--  1 pywcc pywcc    0 Apr  8 22:44 README.md
-rw-rw-r--  1 pywcc pywcc   85 Apr  8 22:44 main.py
-rw-rw-r--  1 pywcc pywcc  152 Apr  8 22:44 pyproject.toml
-rw-rw-r--  1 pywcc pywcc  126 Apr  8 22:51 uv.lock

# 运行项目
uv run main.py

# 安装依赖，如fastMCP
uv add fastmcp
uv pip install fastmcp
# 指定开发环境环境：--dev
# 指定生成环境：--production
uv add "numpy; python_version >= '3.11'; sys_platform == 'linux'"

# 删除依赖
uv remove fastmcp
uv pip uninstall fastmcp

# 查看依赖
uv pip list

# 导出依赖
uv pip freeze > requirements.txt
uv pip compile pyproject.toml -o requirements.txt

# 批量安装
uv pip install -r requirements.txt
uv add -r requirements.txt
uv pip install -r pyproject.toml

# 清除缓存
uv cache clean
uv pip cache purge

# 项目依赖树
uv tree

报错：No solution found when resolving dependencies for split (python_full_version == '3.9.*'):

解决办法：退出其他python虚拟环境，只使用uv创建的虚拟环境，检查pyproject.toml和 .python-version、uv.lock中requires-python版本，修改pyproject.toml中python版本和删除uv.lock，执行uv sync

5. 设置镜像源

临时设置依赖镜像源：

uv add --default-index https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple fastmcp

设置依赖镜像源：

vi ~/.bashrc
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 额外镜像地址
export EXTRA_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

或者

基于项目目录下pyproject.toml添加配置

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

基于项目目录下uv.toml添加配置

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

docker中使用 Using uv in Docker | uv (astral.sh)