uv 是一个使用 Rust 编写的极速 Python 软件包和项目管理器，pip 的替代工具。uv 可以管理项目依赖关系和环境，支持锁定文件、工作空间等，类似于 rye 或 poetry。
介绍
- 替代 pip、pip-tools、pipx、poes、pyenv、twine、virtualenv 等的单一工具
- 比 pip 快 10-100 倍
- ️ 提供全面的项目管理，具有通用锁文件
- 运行脚本，支持内联依赖元数据
- 安装和管理 Python 版本
- 运行和安装以 Python 包形式发布的工具
- 包含一个与 pip 兼容的界面，通过熟悉的 CLI 提高性能
- 支持 Cargo 风格的工作区，可扩展项目
- 磁盘空间效率高，全局缓存可实现重复数据依赖
- 无需 Rust 或 Python，即可通过 curl 或 pip 安装
- 支持 macOS、Linux 和 Windows
安装
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# With pip.
pip install uv
# Or pipx.
pipx install uv
# 自更新
uv self update
使用
# 初始化项目
$ uv init example
$ cd example
$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
+ example==0.1.0 (from file:///home/user/example)
+ ruff==0.5.0
$ uv run ruff check
All checks passed!
$ uv lock
Resolved 2 packages in 0.33ms
$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms
help
uv --help
uv pip --help
uv pip install --help
$ uv --help
An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
Commands:
run Run a command or script
init Create a new project
add Add dependencies to the project
remove Remove dependencies from the project
sync Update the project's environment
lock Update the project's lockfile
export Export the project's lockfile to an alternate format
tree Display the project's dependency tree
tool Run and install commands provided by Python packages
python Manage Python versions and installations
pip Manage Python packages with a pip-compatible interface
venv Create a virtual environment
build Build Python packages into source distributions and wheels
publish Upload distributions to an index
cache Manage uv's cache
self Manage the uv executable
version Display uv's version
help Display documentation for a command
Cache options:
-n, --no-cache Avoid reading from or writing to the cache, instead using a temporary directory for the
duration of the operation [env: UV_NO_CACHE=]
--cache-dir <CACHE_DIR> Path to the cache directory [env: UV_CACHE_DIR=]
Python options:
--python-preference <PYTHON_PREFERENCE> Whether to prefer uv-managed or system Python installations [env:
UV_PYTHON_PREFERENCE=] [possible values: only-managed, managed, system,
only-system]
--no-python-downloads Disable automatic downloads of Python. [env:
"UV_PYTHON_DOWNLOADS=never"]
Global options:
-q, --quiet
Do not print any output
-v, --verbose...
Use verbose output
--color <COLOR_CHOICE>
Control the use of color in output [possible values: auto, always, never]
--native-tls
Whether to load TLS certificates from the platform's native certificate store [env: UV_NATIVE_TLS=]
--offline
Disable network access [env: UV_OFFLINE=]
--allow-insecure-host <ALLOW_INSECURE_HOST>
Allow insecure connections to a host [env: UV_INSECURE_HOST=]
--no-progress
Hide all progress outputs [env: UV_NO_PROGRESS=]
--directory <DIRECTORY>
Change to the given directory prior to running the command
--project <PROJECT>
Run the command within the given project directory
--config-file <CONFIG_FILE>
The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
--no-config
Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) [env: UV_NO_CONFIG=]
-h, --help
Display the concise help for this command
-V, --version
Display the uv version
Use `uv help` for more details.
python 版本管理
$ uv python install 3.10 3.11 3.12
# 创建 env，不加环境路径的话默认是保存在当前的 .venv 目录下
uv venv
# 指定环境保存目录
uv venv /path/to/venv
# 指定Python版本，注意需要对应版本的Python已经安装，--python 同 -p
$ uv venv --python 3.12
$ uv venv --python 3.12.0
$ uv run --python pypy@3.8 -- python --version
# 使用当前目录中的特定 Python 版本
$ uv python pin 3.11
# 使用
source venv/bin/activate
pip 子命令
功能类似于 pip，如 uv pip install -r ...
# 从 pypi上安装包，默认安装最新版本
uv pip install flask
# 从镜像网站上安装包
uv pip install flask -i https://pypi.tuna.tsinghua.edu.cn/simple
# 更新包版本
uv pip install -U flask
# 安装特定版本的包：
uv pip install -U flask==3.0.0
# 从当前目录安装
uv pip install .
# 从当前目录安装，并且支持editable实时更新代码模式
uv pip install -e .
# 卸载
uv pip uninstall flask
说明：
- uv 默认不支持读
pip.conf 配置，在国内的话，包的默认下载速度是比较慢的，需要手动加--index-url/-i 和 --extra-index-url
查看包依赖
uv pip compile my_packages.txt
# 生成指定版本的依赖
uv pip compile --no-annotate my_packages.txt -o requirements.txt
# 查找某个包的依赖
echo tensorflow | uv pip compile --no-annotate -
# 将 requirements.txt 中的版本信息更新到当前虚拟环境
uv pip sync requirements.txt
缓存
- 默认缓存目录
- Linux:
$HOME/.cache/uv
- macOS:
/Users/<user>/Library/Caches/uv
- Windows:
C:/Users/<user>/AppData/Local/uv/cache
- 清理缓存：
uv cache prune
环境变量
# 缓存目录
export UV_CACHE_DIR=/path/to/cache/dir
# 镜像地址
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 额外镜像地址
export EXTRA_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 不使用缓存
export UV_NO_CACHE=0
# 下载包时的超时时间，单位为秒
UV_HTTP_TIMEOUT=30
打包
uv build