2025年6月8日

UV：现代化的 Python 项目管理工具

UV 是一个基于 Rust 开发的高性能 Python 包管理器，专门设计来简化 Python 项目的依赖管理和环境配置。它集成了虚拟环境管理、包安装、项目初始化等多种功能，提供类似 Node.js npm 或 Rust Cargo 的开发体验。

核心优势

极致性能

基于 Rust 实现，依赖解析和包安装速度显著提升
并行下载和安装，充分利用系统资源
智能缓存机制，避免重复下载

️ 统一工具链

一个工具解决多个需求：项目创建、环境管理、依赖安装
标准化的项目结构和配置文件
与现有 Python 生态系统完全兼容

现代化依赖管理

精确的版本锁定，确保跨平台一致性
支持开发/生产环境依赖分离
自动处理依赖冲突和版本兼容性

安装方式

# macOS/Linux 推荐方式
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 通过 pip 安装
pip install uv

安装完成后验证：

uv --version

多用户环境配置

Root 用户安装后的系统级配置

如果您使用 root 用户安装了 UV，但希望普通用户也能使用，可以按照以下步骤配置：

方法一：系统级安装（推荐）

# 1. 使用 root 用户安装到系统目录
sudo curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 将 uv 移动到系统 PATH 目录
sudo mv /root/.local/bin/uv /usr/local/bin/

# 3. 设置正确的权限
sudo chmod 755 /usr/local/bin/uv

# 4. 验证普通用户可以使用
su - username -c "uv --version"

方法二：创建符号链接

# 1. Root 用户正常安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 创建系统级符号链接
sudo ln -s /root/.local/bin/uv /usr/local/bin/uv

# 3. 验证安装
which uv  # 应显示 /usr/local/bin/uv

方法三：配置全局环境变量

# 1. 编辑系统环境变量文件
sudo nano /etc/environment

# 2. 添加以下内容（如果PATH行已存在，则追加）
PATH="/root/.local/bin:$PATH"

# 3. 或者在 /etc/profile 中添加
echo 'export PATH="/root/.local/bin:$PATH"' | sudo tee -a /etc/profile

# 4. 重新加载环境变量
source /etc/profile

# 5. 普通用户重新登录后验证
uv --version

权限和安全考虑

设置适当的目录权限

# 确保 uv 缓存目录对所有用户可访问
sudo mkdir -p /opt/uv-cache
sudo chmod 755 /opt/uv-cache
sudo chown root:root /opt/uv-cache

# 设置全局缓存目录环境变量
echo 'export UV_CACHE_DIR=/opt/uv-cache' | sudo tee -a /etc/environment

用户级配置目录

# 每个用户需要自己的配置目录
# 普通用户首次使用时会自动创建
mkdir -p ~/.local/share/uv
mkdir -p ~/.config/uv

验证多用户配置

# 1. 切换到普通用户测试
sudo -u username uv --version

# 2. 测试创建项目功能
sudo -u username bash -c "
cd /tmp
uv init test-project
cd test-project
uv sync
uv run hello.py
"

# 3. 清理测试项目
rm -rf /tmp/test-project

故障排除

常见问题及解决方案：

权限被拒绝错误

# 检查文件权限
ls -la /usr/local/bin/uv

# 修复权限
sudo chmod 755 /usr/local/bin/uv

找不到命令

# 检查 PATH 配置
echo $PATH

# 临时添加到 PATH
export PATH="/usr/local/bin:$PATH"

# 永久添加到用户配置
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

缓存目录权限问题

# 检查缓存目录权限
ls -la ~/.local/share/uv

# 修复缓存目录权限
chmod -R 755 ~/.local/share/uv

虚拟环境创建失败

# 检查 Python 解释器权限
which python3
ls -la $(which python3)

# 确保用户可以创建虚拟环境
python3 -m venv test-venv
rm -rf test-venv

项目管理流程

创建新项目

# 初始化项目
uv init my-python-app
cd my-python-app

# 查看生成的文件结构
ls -la

UV 会自动创建以下文件：

pyproject.toml – 项目配置和依赖声明
README.md – 项目说明文档
.gitignore – Git 忽略规则
hello.py – 示例代码文件

环境同步

# 创建虚拟环境并安装依赖
uv sync

这个命令会：

检测合适的 Python 版本
创建项目专用的虚拟环境（.venv 目录）
生成锁定文件 uv.lock
安装所有声明的依赖

运行代码

# 使用 UV 运行脚本（自动激活虚拟环境）
uv run hello.py

# 或者激活环境后运行
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows
python hello.py

虚拟环境激活与管理

虽然 UV 推荐使用 uv run 来自动管理虚拟环境，但在某些场景下，手动激活虚拟环境仍然很有用，例如在 IDE 中工作、调试代码或需要持续在环境中工作时。

虚拟环境激活方法

Linux/macOS 系统

# 激活虚拟环境
source .venv/bin/activate

# 或者使用点号简写（等效）
. .venv/bin/activate

# 激活后的提示符会显示环境名
(.venv) $ python --version
(.venv) $ which python

# 退出虚拟环境
(.venv) $ deactivate

Windows 系统

# Windows Command Prompt
.venv\Scripts\activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Git Bash (类似 Linux)
source .venv/Scripts/activate

PowerShell 执行策略问题

在 Windows PowerShell 中，可能遇到执行策略限制：

# 查看当前执行策略
Get-ExecutionPolicy

# 临时允许脚本执行（当前会话）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

# 然后激活环境
.venv\Scripts\Activate.ps1

# 或者直接绕过策略执行
PowerShell -ExecutionPolicy Bypass -File .venv\Scripts\Activate.ps1

激活状态验证

# 激活虚拟环境后验证
source .venv/bin/activate

# 1. 检查 Python 路径
which python
# 应该输出：/path/to/your/project/.venv/bin/python

# 2. 检查 pip 路径
which pip
# 应该输出：/path/to/your/project/.venv/bin/pip

# 3. 查看已安装的包
pip list

# 4. 验证 Python 版本
python --version

# 5. 检查环境变量
echo $VIRTUAL_ENV
# 应该输出：/path/to/your/project/.venv

常用工作流程

开发工作流程

# 1. 进入项目目录
cd my-project

# 2. 同步依赖（如果需要）
uv sync

# 3. 激活虚拟环境
source .venv/bin/activate

# 4. 开发工作
python script.py
pip install some-package  # 临时安装包测试
python -m pytest         # 运行测试

# 5. 退出环境
deactivate

IDE 集成工作流程

# VS Code 示例
# 1. 激活环境
source .venv/bin/activate

# 2. 启动 VS Code（会自动检测虚拟环境）
code .

# 3. 在 VS Code 中：
# - Ctrl+Shift+P -> "Python: Select Interpreter"
# - 选择 .venv/bin/python

# PyCharm 示例
# 1. 打开项目
# 2. File -> Settings -> Project -> Python Interpreter
# 3. 添加已存在的环境：选择 .venv/bin/python

环境管理脚本

自动激活脚本

创建便捷的激活脚本：

# 创建 activate.sh
cat > activate.sh << 'EOF'
#!/bin/bash
if [ -f ".venv/bin/activate" ]; then
    source .venv/bin/activate
    echo "Virtual environment activated: $VIRTUAL_ENV"
    echo "Python version: $(python --version)"
    echo "Pip version: $(pip --version)"
else
    echo "No virtual environment found. Run 'uv sync' first."
fi
EOF

chmod +x activate.sh

# 使用
./activate.sh

跨平台激活脚本

# 创建 env.sh（支持多平台）
cat > env.sh << 'EOF'
#!/bin/bash

# 检测操作系统
if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" || "$OSTYPE" == "win32" ]]; then
    # Windows
    if [ -f ".venv/Scripts/activate" ]; then
        source .venv/Scripts/activate
    else
        echo "Windows virtual environment not found"
        exit 1
    fi
else
    # Linux/macOS
    if [ -f ".venv/bin/activate" ]; then
        source .venv/bin/activate
    else
        echo "Unix virtual environment not found"
        exit 1
    fi
fi

echo "Environment activated: $VIRTUAL_ENV"
EOF

chmod +x env.sh

环境隔离验证

# 在项目外测试环境隔离
cd /tmp

# 1. 未激活环境时
python -c "import sys; print(sys.path)"

# 2. 激活项目环境
source /path/to/your/project/.venv/bin/activate

# 3. 激活后再次检查
python -c "import sys; print(sys.path)"
# 应该看到 .venv 路径在前面

# 4. 安装包测试隔离性
pip install some-test-package
pip list  # 只在虚拟环境中可见

# 5. 退出环境
deactivate

# 6. 再次检查（包应该不可见）
python -c "import some_test_package"  # 应该报错

多环境管理

管理多个项目环境

# 项目1
cd ~/project1
source .venv/bin/activate
echo "Working in: $VIRTUAL_ENV"
# ... 工作 ...
deactivate

# 项目2
cd ~/project2
source .venv/bin/activate
echo "Working in: $VIRTUAL_ENV"
# ... 工作 ...
deactivate

环境状态脚本

# 创建环境状态检查脚本
cat > check_env.sh << 'EOF'
#!/bin/bash

echo "=== Python Environment Status ==="
echo "Virtual Environment: ${VIRTUAL_ENV:-"Not activated"}"
echo "Python Path: $(which python)"
echo "Python Version: $(python --version)"
echo "Pip Path: $(which pip)"

if [ -n "$VIRTUAL_ENV" ]; then
    echo "=== Installed Packages ==="
    pip list --format=columns
else
    echo "No virtual environment activated"
fi
EOF

chmod +x check_env.sh

常见问题与解决方案

1. 激活脚本不存在

# 检查虚拟环境是否正确创建
ls -la .venv/

# 如果不存在，重新创建
uv sync

# 或手动创建虚拟环境
uv venv

2. 权限问题

# 检查权限
ls -la .venv/bin/activate

# 修复权限
chmod +x .venv/bin/activate

3. 路径包含空格

# 如果项目路径包含空格，使用引号
source "/path/with spaces/.venv/bin/activate"

4. 环境变量冲突

# 清理可能冲突的环境变量
unset PYTHONPATH
unset PYTHONHOME

# 然后重新激活
source .venv/bin/activate

UV vs 传统激活方式对比

方式	优点	缺点	适用场景
`uv run`	自动管理，简单快捷	每次都需要前缀	脚本执行，CI/CD
`source activate`	持续激活，IDE 友好	需手动管理	开发调试，IDE 集成

最佳实践建议

日常开发：使用 source .venv/bin/activate 激活环境进行开发
脚本运行：使用 uv run 执行单次命令
CI/CD：优先使用 uv run 避免状态管理复杂性
IDE 集成：激活环境后启动 IDE，确保正确的解释器检测
团队协作：在文档中同时提供两种方式的使用说明

Python 版本管理

UV 提供了强大的 Python 版本管理功能，可以自动下载、安装和管理不同版本的 Python，无需手动安装或使用其他工具。

安装 Python 版本

基本安装命令

# 安装特定版本的 Python
uv python install 3.12

# 安装多个版本
uv python install 3.11 3.12 3.13

# 安装最新版本
uv python install 3.12.latest

# 安装预览版本
uv python install 3.13.0b4

查看可用版本

# 列出所有可安装的 Python 版本
uv python list --all

# 查看已安装的版本
uv python list

# 查看当前使用的版本
uv python find

安装示例

# 详细安装过程示例
$ uv python install 3.12
Searching for Python installations
Installed Python 3.12.7 in 2.5s
 + cpython-3.12.7-linux-x86_64-gnu

# 验证安装
$ uv python list
cpython-3.11.9-linux-x86_64-gnu    /home/user/.local/share/uv/python/cpython-3.11.9-linux-x86_64-gnu/bin/python3
cpython-3.12.7-linux-x86_64-gnu    /home/user/.local/share/uv/python/cpython-3.12.7-linux-x86_64-gnu/bin/python3

创建指定版本的虚拟环境

使用 uv venv 创建环境

# 创建使用 Python 3.12 的虚拟环境
uv venv --python 3.12

# 指定虚拟环境名称
uv venv myenv --python 3.12

# 创建在指定路径
uv venv /path/to/venv --python 3.12

# 使用具体的版本号
uv venv --python 3.12.7

项目中指定 Python 版本

# 方法一：在创建项目时指定版本
uv init my-project --python 3.12

# 方法二：在现有项目中设置版本
echo "3.12" > .python-version
uv sync

# 方法三：在 pyproject.toml 中指定
# 编辑 pyproject.toml 文件

在 pyproject.toml 中配置：

[project]
requires-python = ">=3.12,<3.13"

# 或者更灵活的版本要求
requires-python = ">=3.11"

实际使用流程

完整的项目创建流程

# 1. 确保已安装所需的 Python 版本
uv python install 3.12

# 2. 创建项目并指定 Python 版本
uv init my-web-app --python 3.12
cd my-web-app

# 3. 查看自动生成的版本配置
cat .python-version  # 输出: 3.12

# 4. 同步环境（会使用指定的 Python 版本）
uv sync

# 5. 验证 Python 版本
uv run python --version  # 输出: Python 3.12.x

切换现有项目的 Python 版本

# 当前项目使用 Python 3.11，想切换到 3.12

# 1. 安装新版本（如果未安装）
uv python install 3.12

# 2. 更新版本文件
echo "3.12" > .python-version

# 3. 删除旧环境
rm -rf .venv

# 4. 重新创建环境
uv sync

# 5. 验证版本
uv run python --version

与其他工具的兼容性

UV 不仅提供了现代化的包管理体验，还保持了对现有 Python 生态工具的完全兼容。您可以在 UV 项目中直接使用 pip 命令，也可以在现有的 Poetry 项目中无缝使用 UV。

UV 内置的 pip 命令支持

UV 内置了完整的 pip 命令接口，您可以直接使用熟悉的 pip 语法：

# 在UV管理的虚拟环境中直接使用pip命令
uv pip install requests
uv pip install numpy==1.24.0
uv pip install -r requirements.txt
uv pip install -e .
uv pip install git+https://github.com/user/repo.git

# pip的高级功能也完全支持
uv pip install --upgrade package
uv pip install --no-deps package
uv pip install --index-url https://pypi.org/simple package
uv pip install --trusted-host example.com package

# 查看和管理包
uv pip list
uv pip show package
uv pip freeze
uv pip check

# 卸载包
uv pip uninstall package
uv pip uninstall -r requirements.txt

传统 requirements.txt 工作流支持

# 1. 从requirements.txt安装依赖
uv pip install -r requirements.txt

# 2. 导出当前环境到requirements.txt
uv pip freeze > requirements.txt

# 3. 安装开发依赖
uv pip install -r requirements-dev.txt

# 4. 约束文件支持
uv pip install -r requirements.txt -c constraints.txt

# 5. 支持pip的所有参数
uv pip install \
    --requirement requirements.txt \
    --constraint constraints.txt \
    --no-deps \
    --force-reinstall \
    package_name

Poetry 项目兼容性

UV 可以直接读取和使用 Poetry 格式的 pyproject.toml 配置：

# 在现有Poetry项目中使用UV
cd existing-poetry-project

# UV会自动读取Poetry的配置格式
uv sync  # 读取[tool.poetry.dependencies]

# 继续使用UV命令管理项目
uv add requests  # 自动转换为Poetry格式
uv run python script.py

Poetry 配置格式支持：

# UV完全支持这种Poetry格式的pyproject.toml
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "My awesome project"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"
numpy = ">=1.20.0,<2.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
black = "^22.0.0"
flake8 = "^5.0.0"

[tool.poetry.scripts]
my-cli = "myproject.cli:main"

混合工作流示例

在 Poetry 项目中使用 UV：

# 现有Poetry项目
ls -la
# pyproject.toml (Poetry格式)
# poetry.lock

# 直接使用UV（会保持Poetry格式）
uv sync                    # 安装Poetry定义的依赖
uv add flask              # 添加新依赖（更新Poetry格式）
uv run python app.py      # 运行应用
uv pip list               # 查看安装的包

在 pip 项目中使用 UV：

# 现有pip项目
ls -la
# requirements.txt
# requirements-dev.txt

# 使用UV管理环境
uv venv                                    # 创建虚拟环境
uv pip install -r requirements.txt        # 安装生产依赖
uv pip install -r requirements-dev.txt    # 安装开发依赖
uv run python app.py                      # 运行应用

# 可选：转换为现代格式
uv init --no-readme .                     # 创建pyproject.toml
# 然后手动迁移依赖或使用脚本

UV 对 setuptools 的支持

# 传统setup.py项目
ls -la
# setup.py
# setup.cfg

# UV完全支持传统格式
uv pip install -e .      # 可编辑模式安装
uv sync                  # 如果有pyproject.toml
uv run python setup.py test

环境隔离与 pip 兼容性

# UV创建的虚拟环境与pip完全兼容
uv venv
source .venv/bin/activate

# 在激活的环境中可以直接使用系统pip
pip install package      # 直接使用系统pip
python -m pip install package

# 或者使用UV的pip接口（推荐）
uv pip install package  # 使用UV的高性能pip实现

依赖解析兼容性

# UV的依赖解析器兼容所有标准格式

# PEP 508依赖规范
uv add "requests>=2.25.0,<3.0.0"
uv add "django>=4.0; python_version>='3.8'"
uv add "typing-extensions; python_version<'3.8'"

# 额外依赖支持
uv add "fastapi[all]"
uv add "sqlalchemy[postgresql,mysql]"

# URL依赖支持
uv add "package @ git+https://github.com/user/repo.git"
uv add "package @ file:///path/to/local/package"

构建系统兼容性

UV 支持所有标准的 Python 构建系统：

# setuptools
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm"]
build-backend = "setuptools.build_meta"

# Poetry
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

# Hatchling
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# Flit
[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

工具链集成

与 tox 集成：

# tox.ini
[testenv]
deps = uv
commands =
    uv sync
    uv run pytest

[testenv:lint]
commands =
    uv pip install flake8 black
    uv run flake8 src/
    uv run black --check src/

与 pre-commit 集成：

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-sync
        name: UV sync
        entry: uv sync
        language: system
        pass_filenames: false

      - id: pytest
        name: PyTest
        entry: uv run pytest
        language: system
        pass_filenames: false

最佳实践建议

1. 渐进式迁移策略

# 阶段1：在现有项目中使用UV环境管理
cd existing-project
uv venv
uv pip install -r requirements.txt

# 阶段2：开始使用UV命令
uv pip install new-package
uv run python script.py

# 阶段3：迁移到pyproject.toml（可选）
uv init --no-readme .
# 手动迁移依赖配置

2. 团队协作兼容性

# 支持团队中的工具多样性
# 项目同时保持多种格式文件：

ls -la
# pyproject.toml    (UV/Poetry用户)
# requirements.txt  (pip用户)
# uv.lock          (UV锁定文件)

# UV用户工作流
uv sync

# pip用户工作流
pip install -r requirements.txt

# 保持同步的脚本
cat > sync_deps.sh << 'EOF'
#!/bin/bash
# 从pyproject.toml生成requirements.txt
uv pip freeze > requirements.txt
echo "Dependencies synced to requirements.txt"
EOF

3. CI/CD 兼容性

# GitHub Actions - 支持多种工具
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # UV用户路径
      - name: Install UV
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies with UV
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          uv sync

      - name: Run tests with UV
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          uv run pytest

      # 传统pip用户路径（备选）
      - name: Setup Python (fallback)
        if: failure()
        uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: Install dependencies with pip (fallback)
        if: failure()
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests with pip (fallback)
        if: failure()
        run: pytest

依赖管理实践

添加依赖包

# 添加生产依赖
uv add requests numpy

# 添加开发依赖
uv add --group dev pytest black flake8

# 添加特定版本
uv add "django>=4.0,<5.0"

移除依赖

# 移除包及其未使用的依赖
uv remove requests

# 移除开发依赖
uv remove --group dev pytest

环境分类管理

在 pyproject.toml 中自动维护不同环境的依赖：

[project]
name = "my-python-app"
dependencies = [
    "requests>=2.28.0",
    "numpy>=1.24.0",
]

[dependency-groups]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=5.0.0",
]
test = [
    "pytest-cov>=4.0.0",
    "factory-boy>=3.2.0",
]

锁定文件的作用

uv.lock 文件记录了：

所有依赖的精确版本号
依赖关系图谱
跨平台的哈希校验

这确保了团队成员和部署环境中的依赖版本完全一致。

国内镜像源配置

由于网络环境的限制，国内用户使用 UV 下载包时可能会遇到速度慢或连接超时的问题。配置国内镜像源可以显著提升下载速度和稳定性。

配置方法

方法一：环境变量配置（临时生效）

# 设置默认索引源
export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"

# 或者使用清华源
export UV_DEFAULT_INDEX="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

# Windows PowerShell
$env:UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"

方法二：全局配置文件（推荐）

创建或编辑 UV 的全局配置文件：

Linux/macOS：~/.config/uv/uv.toml
Windows：%APPDATA%/uv/uv.toml

# 创建配置目录（如果不存在）
mkdir -p ~/.config/uv

# 创建配置文件
cat > ~/.config/uv/uv.toml << 'EOF'
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

# 如果使用 HTTP 源，需要添加安全配置
# trusted-host = ["mirrors.aliyun.com"]
EOF

方法三：项目级别配置

在项目的 pyproject.toml 文件中添加配置：

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

[tool.uv.pip]
index-url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

方法四：命令行参数

# 临时使用指定源安装包
uv add requests --index-url https://mirrors.aliyun.com/pypi/simple/

# 同步依赖时使用指定源
uv sync --index-url https://mirrors.aliyun.com/pypi/simple/

常用国内镜像源

镜像站	URL	特点
阿里云	`https://mirrors.aliyun.com/pypi/simple/`	速度快，稳定性好
清华大学	`https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple`	老牌镜像，更新及时
腾讯云	`https://mirrors.cloud.tencent.com/pypi/simple/`	速度快，商业支持
华为云	`https://mirrors.huaweicloud.com/repository/pypi/simple/`	企业级稳定
网易	`https://mirrors.163.com/pypi/simple/`	老牌服务商
豆瓣	`https://pypi.douban.com/simple/`	简单易用

一键配置脚本

基于社区提供的脚本，可以一行命令完成配置：

# 使用阿里云源
curl -fsSL https://gh-proxy.com/raw.githubusercontent.com/waketzheng/carstino/main/pip_conf.py -o pip_conf.py && python pip_conf.py aliyun --uv

# 使用清华源
curl -fsSL https://gh-proxy.com/raw.githubusercontent.com/waketzheng/carstino/main/pip_conf.py -o pip_conf.py && python pip_conf.py qinghua --uv

# 清理临时文件
rm pip_conf.py

验证配置

# 查看当前配置
uv pip config list

# 测试下载速度
time uv add requests

# 查看使用的源
uv add requests --dry-run --verbose

高级配置

多源配置

# ~/.config/uv/uv.toml
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

[[index]]
url = "https://pypi.org/simple/"

私有源配置

# 企业内部私有源
[[index]]
url = "https://internal.company.com/pypi/simple/"
default = true

[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"

# 认证配置（如需要）
[tool.uv.pip]
trusted-host = ["internal.company.com"]

条件配置

# 根据网络环境自动选择源
if ping -c 1 mirrors.aliyun.com > /dev/null 2>&1; then
    export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"
else
    export UV_DEFAULT_INDEX="https://pypi.org/simple/"
fi

Python 安装源配置

UV 还可以管理 Python 版本的安装，也可以配置国内源：

# ~/.config/uv/uv.toml
[tool.uv]
python-install-mirror = "https://mirrors.huaweicloud.com/python/"

或者通过环境变量：

export UV_PYTHON_INSTALL_MIRROR="https://mirrors.huaweicloud.com/python/"

网络问题解决

SSL 证书问题

# 信任特定主机
export UV_TRUSTED_HOST="mirrors.aliyun.com,mirrors.tuna.tsinghua.edu.cn"

代理配置

# HTTP 代理
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# 或在配置文件中
[tool.uv.pip]
proxy = "http://proxy.company.com:8080"

性能对比测试

#!/bin/bash
# 镜像源速度测试脚本

sources=(
    "https://pypi.org/simple/"
    "https://mirrors.aliyun.com/pypi/simple/"
    "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
    "https://mirrors.cloud.tencent.com/pypi/simple/"
)

for source in "${sources[@]}"; do
    echo "Testing $source"
    time curl -I "$source" 2>/dev/null | head -1
    echo "---"
done

企业环境建议

统一配置：在企业环境中建议统一配置镜像源
备用源：配置多个镜像源以确保可用性
内网源：有条件的企业可搭建内网 PyPI 镜像
监控告警：监控镜像源的可用性和速度

实用命令速查

命令	功能描述
`uv init [name]`	创建新项目
`uv sync`	同步项目依赖
`uv add <pkg>`	添加依赖包
`uv remove <pkg>`	删除依赖包
`uv run <cmd>`	在项目环境中运行命令
`uv lock`	更新锁定文件
`uv tree`	显示依赖树
`uv pip install <pkg>`	在当前环境安装包

最佳实践建议

1. 项目结构组织

my-project/
├── pyproject.toml    # 项目配置
├── uv.lock          # 依赖锁定（勿手动编辑）
├── README.md        # 项目文档
├── src/             # 源代码目录
│   └── my_project/
└── tests/           # 测试代码

2. 依赖管理策略

生产依赖：项目运行必需的包
开发依赖：开发过程中使用的工具（如测试框架、代码格式化工具）
可选依赖：特定功能的扩展包

3. 版本控制

将 pyproject.toml 和 uv.lock 纳入版本控制
忽略 .venv/ 目录
团队协作时确保使用相同的 UV 版本

4. CI/CD 集成

# 在 CI 环境中的典型流程
uv sync --frozen    # 使用锁定的依赖版本
uv run pytest      # 运行测试
uv run black --check .  # 检查代码格式

迁移指南

从 pip + virtualenv

创建 pyproject.toml，迁移 requirements.txt 内容
运行 uv sync 创建新环境
用 uv run 替代手动激活环境的操作

从 Poetry

UV 可以直接读取现有的 pyproject.toml
运行 uv sync 生成 uv.lock
逐步替换 Poetry 命令为对应的 UV 命令

从 Conda

导出当前环境的包列表
创建新的 UV 项目并添加相应依赖
注意处理 Conda 特有的包（如需要可继续使用 Conda 作为 Python 安装管理器）

故障排除

常见问题及解决方案：

Python 版本不匹配

# 指定 Python 版本
uv sync --python 3.11

依赖冲突

# 查看详细错误信息
uv sync --verbose

网络连接问题

# 使用国内镜像
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple/

清理环境

# 删除虚拟环境重新创建
rm -rf .venv
uv sync

相关资源：

一	二	三	四	五	六	日
« 5月
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30

六狼博客

UV：现代化的 Python 项目管理工具

核心优势

极致性能

️ 统一工具链

现代化依赖管理

安装方式

多用户环境配置

Root 用户安装后的系统级配置

方法一：系统级安装（推荐）

方法二：创建符号链接

方法三：配置全局环境变量

权限和安全考虑

设置适当的目录权限

用户级配置目录

验证多用户配置

故障排除

推荐的部署策略

开发环境

服务器环境

Docker 容器

项目管理流程

创建新项目

环境同步

运行代码

虚拟环境激活与管理

虚拟环境激活方法

Linux/macOS 系统

Windows 系统

PowerShell 执行策略问题

激活状态验证

常用工作流程

开发工作流程

IDE 集成工作流程

环境管理脚本

自动激活脚本

跨平台激活脚本

环境隔离验证

多环境管理

管理多个项目环境

环境状态脚本

常见问题与解决方案

1. 激活脚本不存在

2. 权限问题

3. 路径包含空格

4. 环境变量冲突

UV vs 传统激活方式对比

最佳实践建议

Python 版本管理

安装 Python 版本

基本安装命令

查看可用版本

安装示例

创建指定版本的虚拟环境

使用 uv venv 创建环境

项目中指定 Python 版本

实际使用流程

完整的项目创建流程

切换现有项目的 Python 版本

与其他工具的兼容性

UV 内置的 pip 命令支持

传统 requirements.txt 工作流支持

Poetry 项目兼容性

混合工作流示例

UV 对 setuptools 的支持

环境隔离与 pip 兼容性

依赖解析兼容性

构建系统兼容性

工具链集成

最佳实践建议

依赖管理实践

添加依赖包

移除依赖

环境分类管理

锁定文件的作用

国内镜像源配置

配置方法

方法一：环境变量配置（临时生效）

方法二：全局配置文件（推荐）

方法三：项目级别配置