uv -- Python版本、环境、软件包管理工具

YaoQi

发布于 2026-04-21 10:15:08

3150

uv 是由 Astral 公司开发的一款 Rust 编写的 Python 包管理器和环境管理器。

uv 可以替代 pip、virtualenv、pip-tools 等工具，提供依赖管理、虚拟环境创建、Python 版本管理等一站式服务。

官网文档：https://uv.doczh.com/

安装

macOS：

brew install uv

Windows：

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

Linux：

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版本，缓存等都是各账号独立的。

共享安装的python版本：

设置全局环境变量 UV_PYTHON_INSTALL_DIR

通过指定一个所有用户都有权读取的公共目录，让 uv 将 Python 安装到那里。

# 创建公共存放目录
sudo mkdir -p /opt/uv/python
sudo 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)"' >> ~/.bashrc
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
# zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc
# fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
echo 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish
# Elvish
echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv
echo 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv
# PowerShell
if (!(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 compinit
compinit

更多安装方法，见官网说明：

https://uv.doczh.com/getting-started/installation/

管理Python版本

uv python list # 查看可用 Python 版本
uv python install # 安装 Python 版本
uv python uninstall # 卸载 Python 版本
uv python find # 查找已安装的 Python 版本所在路径

安装的Python版本需要创建对应的虚拟环境进行使用。

不指定Python版本，默认使用当前系统中安装的最新版本。

如果指定使用了没有安装的版本，uv会自动下载安装。

固定使用特定 Python 版本:

uv python pin 3.14

会在当前路径创建.python-version, 内含固定的python版本号。如果当前路径没有固定版本号或创建虚拟环境，uv 命令会搜寻它上层各级父路径。

创建虚拟环境

uv venv -p 3.14 # 创建虚拟环境，后边可跟虚拟环境路径

也可以先pin一个确定版本，再创建虚拟环境：

uv python pin 3.14
uv 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.py
uv 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 time
from rich.progress import track

for i in track(range(20), description="For example:"):
    time.sleep(0.05)

用--with参数指定依赖项：

uv run --with rich example.py
uv run --with'rich>12,<13' example.py

可以通过重复使用 --with 选项来请求多个依赖项。

注意：如果在项目中使用 uv run，这些依赖项将作为项目依赖项的补充包含在内。若要避免这种行为，请使用 --no-project 标志。

Python 最近为内联脚本元数据添加了一种标准格式。它允许脚本选择 Python 版本并定义依赖项。

使用 uv init --script 来初始化带有内联元数据的脚本：

%uv init --script example.py --python 3.12
Initialized 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 httpx
print(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 ruff
uv tool install 'httpie>0.1.0'
uv tool install git+https://github.com/httpie/cli
uv tool upgrade ruff
uv tool upgrade --all

uvx install upgrade 还支持 --python 指定要使用的python解释器版本。

命令行提示

缓存管理

uv cache clean 会从缓存目录中删除所有缓存条目，将其完全清空。

uv cache clean ruff 会删除 ruff 包的所有缓存条目，这对于使单个或有限的一组包的缓存失效很有用。

uv cache prune 会删除所有未使用的缓存条目。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-04-14，如有侵权请联系 cloudcommunity@tencent.com 删除

python

本文分享自漫跑的小兔微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度

uv -- Python版本、环境、软件包管理工具

uv -- Python版本、环境、软件包管理工具

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐