uv 是由 Astral 公司开发的一款 Rust 编写的 Python 包管理器和环境管理器。
uv 可以替代 pip、virtualenv、pip-tools 等工具，提供依赖管理、虚拟环境创建、Python 版本管理等一站式服务。
官网文档：https://uv.doczh.com/
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh
这一步后，uv命令是全局的，但是安装的python版本，缓存等都是各账号独立的。设置全局环境变量 UV_PYTHON_INSTALL_DIR
通过指定一个所有用户都有权读取的公共目录，让 uv 将 Python 安装到那里。
# 创建公共存放目录sudo mkdir -p /opt/uv/pythonsudo chmod 777 /opt/uv/python # 允许写入，或者设置为特定用户组# 配置全局环境变量：echo 'UV_PYTHON_INSTALL_DIR="/opt/uv/python"' | sudo tee -a /etc/environment
重新登录终端即可生效。
这样，任何用户运行 uv python install 时，Python 都会被安装到 /opt/uv/python。
uv 具有智能发现机制。只要用户设置了上述环境变量，他们运行 uv run 或 uv venv 时，uv 就会优先去这个全局目录里找对应的版本，而不会重复下载。
# bash echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrcecho 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc# zshecho 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrcecho 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc# fishecho 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fishecho 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish# Elvishecho 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elvecho 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv# PowerShellif (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force}Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'if (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force}Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'
完成后请重启 shell 或重新加载 shell 配置文件zsh提示(eval):6261: command not found: compdef 解决：打开~/.zshrc文件,将以下代码加入到文件内容顶部autoload -Uz compinitcompinit
https://uv.doczh.com/getting-started/installation/
uv python list # 查看可用 Python 版本uv python install # 安装 Python 版本uv python uninstall # 卸载 Python 版本uv python find # 查找已安装的 Python 版本所在路径
安装的Python版本需要创建对应的虚拟环境进行使用。不指定Python版本，默认使用当前系统中安装的最新版本。如果指定使用了没有安装的版本，uv会自动下载安装。会在当前路径创建.python-version, 内含固定的python版本号。如果当前路径没有固定版本号或创建虚拟环境，uv 命令会搜寻它上层各级父路径。uv venv -p 3.14 # 创建虚拟环境，后边可跟虚拟环境路径
也可以先pin一个确定版本，再创建虚拟环境：
uv python pin 3.14uv venv
使用虚拟环境和其他虚拟环境一样，使用source (或 .) 激活：
source .venv/bin/activate
使用 deactivate 退出虚拟环境。
包管理
uv pip 提供了和pip兼容的命令格式
uv pip install # 将包安装到当前环境uv pip show # 显示已安装包的详细信息uv pip freeze # 列出已安装包及其版本uv pip check # 检查当前环境的包兼容性uv pip list # 列出已安装包uv pip uninstall # 卸载包uv pip tree # 查看环境的依赖树
Python 环境的查找
运行诸如 uv pip sync 或 uv pip install 这类会改变环境的命令时，uv 会按以下顺序查找虚拟环境： - 基于 VIRTUAL_ENV 环境变量激活的虚拟环境。 - 基于 CONDA_PREFIX 环境变量激活的 Conda 环境。 - 当前工作目录或最近父目录下 .venv 中的虚拟环境。
开机启动等工作路径不明的情况，可以使用参数 --directory 指定其工作路径，以查找正确的虚拟环境。
项目管理
创建和开发带有 pyproject.toml 的 Python 项目。
uv init # 创建新 Python 项目uv add # 为项目添加依赖uv remove # 从项目移除依赖uv sync # 同步项目依赖到环境uv lock # 为项目依赖创建锁文件uv tree # 查看项目依赖树uv build # 构建项目为分发包uv publish # 发布项目到PyPi
% cat pyproject.toml [project]name = "project name"version = "0.1.0"description = "项目描述"readme = "README.md"requires-python = ">=3.14"dependencies = ["pdfplumber", "pypdf"]
在你首次运行项目命令（如 uv run、uv sync 或 uv lock）时，uv 还会在项目根目录中创建一个虚拟环境和 uv.lock 文件。
运行脚本
用于执行简单的Python脚本，不创建项目和虚拟环境（uv自动创建临时环境）
对于没有依赖项或只依赖标准库的脚本
可以直接用uv run 运行：
uv run example.pyuv run example.py test # 带参数执行uv run --directory /path/to/working/dir # 设置运行路径uv run --python 3.10 example.py # 使用特定的 Python 版本uv run --no-project example.py # 在项目路径，但不使用项目环境运行
对于有依赖项的脚本，比如：
import timefrom rich.progress import trackfor i in track(range(20), description="For example:"): time.sleep(0.05)
用--with参数指定依赖项：
uv run --with rich example.pyuv run --with'rich>12,<13' example.py
可以通过重复使用 --with 选项来请求多个依赖项。
注意：如果在 项目 中使用 uv run，这些依赖项将作为项目依赖项的 补充 包含在内。若要避免这种行为，请使用 --no-project 标志。
Python 最近为内联脚本元数据添加了一种标准格式。它允许脚本选择 Python 版本并定义依赖项。使用 uv init --script 来初始化带有内联元数据的脚本：%uv init --script example.py --python 3.12Initialized script at `example.py`% cat example.py # /// script# requires-python = ">=3.12"# dependencies = []# ///def main() -> None: print("Hello from example.py!")if __name__ == "__main__": main()
使用 uv add --script 来添加依赖项：% uv add --script example.py 'requests<3' 'rich'Resolved 9 packages in 1.46s% cat example.py # /// script# requires-python = ">=3.12"# dependencies = [# "requests<3",# "rich>=14.3.2",# ]# ///def main() -> None: print("Hello from example.py!")if __name__ == "__main__": main()
可以添加 shebang，使脚本无需使用 uv run 即可执行 —— 这样可以轻松运行位于 PATH 或当前文件夹中的脚本：#!/usr/bin/env -S uv run --script# /// script# requires-python = ">=3.12"# dependencies = ["httpx"]# ///import httpxprint(httpx.get("https://example.com"))
许多 Python 软件包提供了可用作工具的应用程序。uv 对轻松调用和安装工具提供了专门支持。这些应用程序用 uv tool 命令来运行和管理，可在不安装工具的情况下调用它。% uv tool run cowsay -t hello -c tux# 或% uvx cowsay -t hello -c tux
uvx 作为 uv tool run 的别名提供，以方便使用，与工具交互的所有其他命令都需要完整的 uv tool 前缀。uvx ruff@0.3.0 check # 指定特定版本uvx --from httpie http # 从特定软件包调用uvx --from 'ruff>0.2.0,<0.3.0' ruff check # 指定版本范围uvx --from git+https://github.com/httpie/cli httpie # 从git拉取uvx --from git+https://github.com/httpie/cli@master httpie # 从特定分支，也可以是标签，提交拉取
uv tool install ruffuv tool install 'httpie>0.1.0'uv tool install git+https://github.com/httpie/cliuv tool upgrade ruffuv tool upgrade --all
uvx install upgrade 还支持 --python 指定要使用的python解释器版本。uv cache clean 会从缓存目录中删除所有缓存条目，将其完全清空。uv cache clean ruff 会删除 ruff 包的所有缓存条目，这对于使单个或有限的一组包的缓存失效很有用。 uv cache prune 会删除所有未使用的缓存条目。
