uv安装介绍
uv 安装、Python 版本管理、虚拟环境、依赖管理和 CI/CD 使用建议。
uv
uv 是一个高性能 Python 包管理和项目管理工具，可以替代部分 pip、pip-tools、venv、virtualenv、poetry 和 pyenv 的日常工作。它适合本地开发、CI/CD 构建、Python 脚本运行和多项目依赖管理。
适用场景
- 快速创建 Python 虚拟环境。
- 管理项目依赖和锁定文件。
- 安装和切换 Python 版本。
- 在 CI/CD 中复现一致的依赖环境。
- 临时运行 Python 工具或脚本。
- 替代
pip install提升依赖安装速度。
安装 uv
macOS / Linux 可以使用官方安装脚本：
curl -LsSf https://astral.sh/uv/install.sh | sh
安装完成后重新加载 shell：
source ~/.zshrc
验证版本：
uv --version
如果使用 Homebrew：
brew install uv
如果已经有 Python 和 pip，也可以使用 pip 安装：
pip install uv
管理 Python 版本
查看可安装的 Python 版本：
uv python list
安装指定 Python 版本：
uv python install 3.12
查看已安装 Python：
uv python list --only-installed
在当前项目中指定 Python 版本：
uv python pin 3.12
这会在项目中生成 .python-version 文件，后续 uv 会优先使用该版本。
创建虚拟环境
在当前目录创建 .venv：
uv venv
指定 Python 版本创建虚拟环境：
uv venv --python 3.12
激活虚拟环境：
source .venv/bin/activate
确认当前 Python：
which python
python --version
初始化项目
创建新项目：
uv init demo-service
cd demo-service
在已有目录初始化：
uv init
初始化后通常会生成：
pyproject.toml
README.md
main.py
管理依赖
添加运行依赖：
uv add requests
uv add fastapi uvicorn
添加开发依赖：
uv add --dev pytest ruff mypy
删除依赖：
uv remove requests
同步依赖环境：
uv sync
严格按锁文件同步，不允许自动更新锁文件：
uv sync --frozen
运行命令
在项目环境中运行 Python：
uv run python --version
运行脚本：
uv run python main.py
运行测试：
uv run pytest
运行格式化或检查工具：
uv run ruff check .
uv run ruff format .
临时运行一个未安装到项目里的工具：
uvx ruff check .
uvx httpie https://example.com
替代 pip 使用
安装包：
uv pip install requests
从 requirements.txt 安装：
uv pip install -r requirements.txt
导出当前环境：
uv pip freeze
CI/CD 使用建议
典型流水线步骤：
uv python install 3.12
uv sync --frozen
uv run pytest
uv run ruff check .
如果构建机网络不稳定，建议缓存以下目录：
~/.cache/uv
.venv
容器构建中可以先复制锁文件，提高依赖层缓存命中率：
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
常用命令
| 命令 | 说明 |
|---|---|
uv --version | 查看 uv 版本 |
uv init | 初始化 Python 项目 |
uv python install 3.12 | 安装 Python 3.12 |
uv python pin 3.12 | 固定项目 Python 版本 |
uv venv | 创建虚拟环境 |
uv add requests | 添加运行依赖 |
uv add --dev pytest | 添加开发依赖 |
uv remove requests | 删除依赖 |
uv sync | 同步项目环境 |
uv sync --frozen | 严格按锁文件同步 |
uv run pytest | 在项目环境中运行命令 |
uvx ruff check . | 临时运行工具 |
常见问题
uv: command not found
确认 uv 是否安装成功：
which uv
uv --version
如果安装脚本提示已安装但命令不可用，检查 shell 配置是否加载了 uv 安装路径。
echo $PATH
source ~/.zshrc
Python 版本不符合预期
检查项目是否存在 .python-version：
cat .python-version
uv python list --only-installed
uv run python --version
如需重新固定版本：
uv python install 3.12
uv python pin 3.12
uv sync
依赖安装失败
优先确认锁文件和 Python 版本：
uv run python --version
uv sync --frozen
如果是网络问题，可以重试或检查代理、镜像源和构建机网络策略。
CI 和本地依赖不一致
确认是否提交了锁文件：
ls pyproject.toml uv.lock
CI 中使用：
uv sync --frozen
不要在 CI 中直接执行会隐式更新依赖的命令，除非流水线目标就是更新锁文件。
关联文档
- Python 项目依赖管理规范。
- CI/CD Python 构建环境。
- Ruff / Pytest / Mypy 工具链配置。