2026年UV包管理器基础使用教程

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

 
  
    
     
     uv 是 Astral 团队用 Rust 写的超高速 Python 包管理器，比 pip 快 10-100 倍。它集成了包管理、虚拟环境、Python 版本管理、项目脚本运行等功能，是 pip + venv + pipx + pyenv 的完美替代品。 
     
  
    
     
     # macOS / Linux  
     curl -LsSf https://astral.sh/uv/install.sh | sh 
     Windows (PowerShell) 
     irm https://astral.sh/uv/install.ps1 | iex 
     通过 pip 安装（不推荐，但应急可以用） 
     pip install uv 
     通过 Homebrew (macOS) 
     brew install uv

安装后验证：

uv –version uv 0.7.x (2026)

💡 安装脚本会自动将 uv 加入 PATH。如果终端找不到命令，重新打开终端或执行 source ~/.bashrc / source ~/.zshenv。

# 新建项目目录并初始化（推荐） uv init my_project cd my_project
 现有目录中初始化
 cd existing_project uv init
 指定 Python 版本初始化
 uv init my_project –python 3.12

初始化后会生成以下文件：

my_project/ ├── pyproject.toml # 项目配置（核心文件） ├── .python-version # Python 版本锁定 ├── hello.py # 示例文件 └── README.md

[project] name = "my-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.11" dependencies = [] [project.scripts] hello = "hello:main"

# 安装包（自动写入 pyproject.toml + 更新锁文件） uv add fastapi uvicorn httpx 安装指定版本
 uv add "requests>=2.28,<3.0"
 安装开发依赖（写入 [dependency-groups] dev 组）
 uv add ruff pytest –dev
 安装可选依赖
 uv add redis –optional cache
 从 requirements.txt 导入
 uv add -r requirements.txt
 从其他 pyproject.toml / setup.py 导入
 uv add -r setup.py

# 卸载包（自动移除依赖 + 更新锁文件） uv remove fastapi 卸载开发依赖
 uv remove pytest –dev

# 生成 / 更新 uv.lock 锁文件 uv lock 按锁文件还原完整环境（部署必备！）
 uv sync
 只安装生产依赖（跳过 dev 组）
 uv sync –production
 安装指定依赖组
 uv sync –group test

💡 uv.lock 是跨平台锁文件，记录每个包的精确版本和哈希。提交到 Git，团队协作时保证环境一致。

# 查看项目依赖树 uv tree 查看过期依赖
 uv pip list –outdated

uv 自动管理虚拟环境，用 uv run 直接执行，不需要手动 activate。

# 运行 Python 脚本 uv run python main.py 运行模块
 uv run python -m http.server 8000
 运行已安装的 CLI 工具
 uv run uvicorn main:app –reload uv run pytest uv run ruff check . uv run mypy src/
 传参（用 – 分隔）
 uv run python main.py – –debug –port 8080

💡 uv run 首次运行时会自动创建虚拟环境并同步依赖，后续直接使用缓存，速度极快。

# 安装指定 Python 版本 uv python install 3.11 uv python install 3.12 3.13 安装最新稳定版
 uv python install
 为当前项目绑定 Python 版本（写入 .python-version）
 uv python pin 3.12
 查看可用的 Python 版本
 uv python list
 查看已安装的版本
 uv python list –only-installed
 查找 Python 可执行文件路径
 uv python find
 卸载某个版本
 uv python uninstall 3.10

💡 uv 可以自动下载并使用你从未安装过的 Python 版本，无需提前手动安装。项目需要 3.11？uv 自己搞定。

如果不想改项目结构，可以把 uv 当作 pip 的高速替代：

# 等价于 pip install（但快 10-100x） uv pip install fastapi uvicorn 安装到指定环境
 uv pip install fastapi –python .venv/bin/python
 从 requirements.txt 安装
 uv pip install -r requirements.txt
 导出依赖为 requirements.txt（兼容旧工具链）
 uv pip freeze > requirements.txt
 编译 pyproject.toml 为 requirements.txt（含完整依赖树）
 uv pip compile pyproject.toml -o requirements.txt
 编译并包含 dev 依赖
 uv pip compile pyproject.toml –extra dev -o requirements-dev.txt
 查看已安装的包
 uv pip list
 查看某个包的详情
 uv pip show fastapi

# 创建虚拟环境 uv venv 指定 Python 版本创建
 uv venv –python 3.12
 指定目录名
 uv venv .my-venv –python 3.11

# 全局安装 CLI 工具（隔离环境，不污染项目） uv tool install ruff uv tool install black uv tool install pre-commit 临时运行一次（不安装，用完即焚）
 uvx ruff check . uvx httpie GET httpbin.org/get uvx cookiecutter gh:audreyr/cookiecutter-pypackage
 查看已安装的全局工具
 uv tool list
 升级全局工具
 uv tool upgrade ruff
 卸载全局工具
 uv tool uninstall ruff
 运行全局工具
 uv tool run ruff check –fix .
 或简写
 uvx ruff check –fix .

💡 uvx = uv tool run，类似 npx，临时执行一个工具而不用全局安装。

uv 内置推荐搭配 Ruff（同样是 Astral 出品，Rust 实现的超快 linter + formatter）：

# 检查代码问题并自动修复 uv run ruff check –fix . 检查但不自动修复（CI 用）
 uv run ruff check .
 格式化代码
 uv run ruff format .
 检查 + 格式化一键搞定
 uv run ruff check –fix . && uv run ruff format .
 在 pyproject.toml 中配置 Ruff

[tool.ruff] line-length = 88 target-version = "py311"
 [tool.ruff.lint] select = ["E", "F", "I", "N", "W", "UP"] ignore = ["E501"]
 [tool.ruff.format] quote-style = "double"

# 只安装生产依赖（跳过 dev/test 组） uv sync –production 导出精简版 requirements.txt（用于 Docker 等场景）
 uv pip compile pyproject.toml -o requirements.txt –no-annotate
 在 Docker 中使用（官方推荐镜像）
 Dockerfile 示例：

FROM python:3.12-slim 安装 uv
 COPY –from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 复制项目文件
 WORKDIR /app COPY pyproject.toml uv.lock ./
 安装依赖（仅生产）
 RUN uv sync –production –no-dev –no-install-project
 复制源码
 COPY . .
 运行
 CMD ["uv", "run", "uvicorn", "main:app", "–host", "0.0.0.0", "–port", "8000"]

适用于 monorepo 或微服务场景：

# 根目录 pyproject.toml [tool.uv.workspace] members = [ "packages/*", "services/*", 
 ]

# packages/auth/ → 共享认证库 packages/models/ → 共享数据模型
 services/api/ → API 服务
 services/worker/ → 后台任务
 同步整个 workspace
 uv sync

# 添加不同分组的依赖 uv add pytest –group test uv add sphinx –group docs uv add ipython –group dev 安装指定分组
 uv sync –group test uv sync –group docs
 安装多个分组
 uv sync –group dev –group test

pyproject.toml 中对应：

[dependency-groups] dev = ["ruff", "mypy"] test = ["pytest", "pytest-cov"] docs = ["sphinx", "sphinx-rtd-theme"]

命令说明 uv init 初始化项目

uv add

添加依赖

uv remove

移除依赖 uv sync 同步环境（按锁文件） uv lock 生成/更新锁文件

uv run

在项目环境中运行命令

uv python install

安装 Python 版本

uv python pin

锁定项目 Python 版本 uv python list 查看可用 Python 版本 uv venv 创建虚拟环境

uv tool install

全局安装工具

uvx

临时运行工具

uv pip install

pip 兼容模式安装 uv pip freeze 导出依赖列表 uv pip compile 编译为 requirements.txt uv tree 查看依赖树 uv self update 更新 uv 自身

uv 用 Rust 写的，速度快 10-100 倍；自带虚拟环境管理、Python 版本管理、锁文件；一个工具搞定 pip + venv + pipx + pyenv。

不需要！uv run 会自动使用项目虚拟环境。如果非要用 source .venv/bin/activate 也行，但没必要。

cd existing_project uv init uv add -r requirements.txt 或者直接用 pip 兼容模式
 uv pip install -r requirements.txt

uv.lock 是 uv 的原生锁文件，包含完整依赖树、哈希校验、跨平台信息。requirements.txt 是传统格式。建议提交 uv.lock，仅在需要兼容旧工具链时导出 requirements.txt。

# GitHub Actions 示例 
              
    
                 
                 uses: astral-sh/setup-uv@v5 
                 run: uv sync 
                 run: uv run pytest

uv 的全局缓存 + 锁文件能让 CI 依赖安装从几分钟降到几秒。

官方文档：https://docs.astral.sh/uv/
GitHub：https://github.com/astral-sh/uv
Ruff（配套 linter）：https://docs.astral.sh/ruff/
Pydantic（推荐 ORM）：https://docs.pydantic.dev/

2026年UV包管理器基础使用教程

Windows (PowerShell)

通过 pip 安装（不推荐，但应急可以用）

通过 Homebrew (macOS)

uv 0.7.x (2026)

现有目录中初始化

指定 Python 版本初始化

安装指定版本

安装开发依赖（写入 [dependency-groups] dev 组）

安装可选依赖

从 requirements.txt 导入

从其他 pyproject.toml / setup.py 导入

卸载开发依赖

按锁文件还原完整环境（部署必备！）

只安装生产依赖（跳过 dev 组）

安装指定依赖组

查看过期依赖

运行模块

运行已安装的 CLI 工具

传参（用 – 分隔）

安装最新稳定版

为当前项目绑定 Python 版本（写入 .python-version）

查看可用的 Python 版本

查看已安装的版本

查找 Python 可执行文件路径

卸载某个版本

安装到指定环境

从 requirements.txt 安装

导出依赖为 requirements.txt（兼容旧工具链）

编译 pyproject.toml 为 requirements.txt（含完整依赖树）

编译并包含 dev 依赖

查看已安装的包

查看某个包的详情

指定 Python 版本创建

指定目录名

临时运行一次（不安装，用完即焚）

查看已安装的全局工具

升级全局工具

卸载全局工具

运行全局工具

或简写

检查但不自动修复（CI 用）

格式化代码

检查 + 格式化一键搞定

在 pyproject.toml 中配置 Ruff

导出精简版 requirements.txt（用于 Docker 等场景）

在 Docker 中使用（官方推荐镜像）

Dockerfile 示例：

安装 uv

复制项目文件

安装依赖（仅生产）

复制源码

运行

packages/models/ → 共享数据模型

services/api/ → API 服务

services/worker/ → 后台任务

同步整个 workspace

安装指定分组

安装多个分组

或者直接用 pip 兼容模式

相关推荐