Python 开发

发布日期: 2025-07-14

更新日期: 2025-07-14

文章字数: 1.9k

阅读时长: 8 分

阅读次数:

uv 和 uvx：现代化 Python 项目管理工具

一、简介

[uv](https://docs.astral.sh/uv/) 是一个用 Rust 编写的极速 Python 包管理器和项目管理工具，由 Astral 开发。它旨在成为 pip、pip-tools、pipx、poetry、pyenv 等工具的现代化替代品，提供统一、快速、可靠的 Python 项目管理体验。

1.1 核心优势

极速性能：比 pip 快 10-100 倍
统一工具：集成多个工具的功能，一个工具解决所有问题
现代化设计：原生支持 PEP 标准，无需 requirements.txt
确定性构建：自动生成锁文件，确保环境可重现
跨平台支持：Windows、macOS、Linux 全平台支持

二、安装 uv

2.1 官方推荐安装方式

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

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2.2 验证安装

uv --version

三、uv vs uvx：核心区别

工具	用途	适用场景
`uv`	项目管理和包管理	开发项目、管理依赖、运行项目代码
`uvx`	临时运行独立工具	运行开发工具、格式化代码、临时使用工具

四、uv：项目管理核心工具

4.1 项目初始化

# 创建新项目
uv init my-project
cd my-project

# 在现有目录初始化
uv init

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

# 指定项目名称
uv init --name "my-awesome-project"

4.2 Python 版本管理

# 查看可用 Python 版本
uv python list

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

# 在项目中固定 Python 版本
uv python pin 3.11

# 查找系统中的 Python
uv python find

4.3 依赖管理

4.3.1 添加依赖

# 添加生产依赖
uv add requests
uv add "django>=4.0,<5.0"

4.3.2 移除依赖

# 移除包
uv remove requests

4.3.3 查看依赖

# 查看依赖树
uv tree

4.4 环境管理

# 同步环境（安装所有依赖）
uv sync

# 重新创建环境
rm -rf .venv
uv sync

4.5 运行代码

# 运行 Python 脚本
uv run script.py

五、uvx：临时工具运行器

5.1 基本用法

# 运行代码格式化工具
uvx black .
uvx isort .

# 运行代码检查工具
uvx flake8 .
uvx pylint src/

# 运行类型检查
uvx mypy src/

5.2 常用工具清单

# 代码格式化
uvx black .                    # Python 代码格式化
uvx isort .                    # 导入语句排序
uvx autopep8 --in-place *.py   # PEP8 格式化

# 代码检查
uvx flake8 .                   # 代码风格检查
uvx pylint src/                # 代码质量分析
uvx mypy src/                  # 静态类型检查
uvx bandit -r src/             # 安全漏洞检查

# 测试工具
uvx pytest                     # 运行测试
uvx coverage run -m pytest     # 测试覆盖率
uvx tox                        # 多环境测试

# 文档工具
uvx sphinx-quickstart          # 初始化 Sphinx 文档
uvx mkdocs new .               # 初始化 MkDocs 项目

# 项目工具
uvx cookiecutter gh:audreyr/cookiecutter-pypackage  # 项目模板
uvx pre-commit install         # Git 钩子工具

六、完整的项目开发流程

6.1 项目创建阶段

# 创建新项目
uv init --name "awesome-project" --python ">=3.9"
cd awesome-project

# 或使用项目模板
uvx cookiecutter gh:audreyr/cookiecutter-pypackage
cd your-project-name
uv init

6.2 依赖配置阶段

# 添加核心依赖
uv add requests fastapi

# 同步环境
uv sync

6.3 开发阶段

# 运行应用
uv run main.py

# 代码格式化
uvx black .
uvx isort .

# 代码检查
uvx flake8 .
uvx mypy src/

# 运行测试
uv run pytest
uv run pytest --cov=src tests/

6.4 代码质量保证

# 完整的代码检查流程
uvx black --check .           # 检查格式
uvx isort --check-only .      # 检查导入排序
uvx flake8 .                  # 风格检查
uvx mypy src/                 # 类型检查
uvx bandit -r src/            # 安全检查
uv run pytest --cov=src      # 测试和覆盖率

6.5 文档编写

# 初始化文档
uvx sphinx-quickstart docs/

# 或使用 MkDocs
uvx mkdocs new .
uvx mkdocs serve

# 生成 API 文档
uvx sphinx-apidoc -o docs/source src/

6.6 构建和发布

# 构建包
uvx build

# 检查包
uvx twine check dist/*

# 发布到 PyPI
uvx twine upload dist/*

# 发布到测试 PyPI
uvx twine upload --repository testpypi dist/*

七、pyproject.toml 配置示例

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

[project]
name = "awesome-project"
version = "0.1.0"
description = "An awesome Python project"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]

dependencies = [
    "requests>=2.28.0",
    "fastapi>=0.100.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
    "mypy>=1.0.0",
]

db = [
    "sqlalchemy>=2.0.0",
    "psycopg2-binary>=2.9.0",
]

test = [
    "pytest-asyncio>=0.18.0",
    "factory-boy>=3.2.0",
    "httpx>=0.24.0",
]

[project.scripts]
awesome-cli = "awesome_project.cli:main"

[project.urls]
Homepage = "https://github.com/username/awesome-project"
Repository = "https://github.com/username/awesome-project"
Issues = "https://github.com/username/awesome-project/issues"

[tool.black]
line-length = 88
target-version = ["py39", "py310", "py311"]

[tool.isort]
profile = "black"
line_length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = "--cov=src --cov-report=term-missing"

[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

八、常见问题和解决方案

8.1 依赖冲突

# 检查冲突
uv check

# 查看详细依赖树
uv tree --show-version-specifiers

# 强制解决冲突
uv lock --resolution-strategy highest

8.2 环境问题

# 重建环境
rm -rf .venv
uv sync

# 清理缓存
uv cache clean

# 检查 Python 安装
uv python list

8.3 性能优化

# 并行安装
uv sync --no-build-isolation

# 使用缓存
uv cache info

# 预编译包
uv add --precompiled numpy

九、最佳实践

9.1 项目结构

my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── docs/
├── pyproject.toml
├── uv.lock
├── README.md
└── .gitignore

9.2 依赖管理

使用语义化版本约束：requests>=2.28.0,<3.0.0
将开发依赖分组管理
定期更新锁文件：uv lock --upgrade
使用可选依赖组分离功能模块

9.3 开发工作流

# 每日开发流程
uv sync                    # 同步环境
uvx black .               # 格式化代码
uvx isort .               # 排序导入
uv run pytest            # 运行测试
uvx flake8 .              # 代码检查

9.4 CI/CD 集成

# GitHub Actions 示例
- name: Install uv
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

- name: Check code quality
  run: |
    uvx black --check .
    uvx flake8 .

十、与其他工具对比

功能	pip/venv	Poetry	uv
安装速度	慢	中等	极快
依赖解析	基础	好	优秀
锁文件	手动	自动	自动
Python 版本管理	需要 pyenv	需要 pyenv	内置
工具运行	需要 pipx	不支持	内置 uvx
学习曲线	平缓	中等	平缓

十一、常见命令速查表

11.1 uv 核心命令

# 项目管理
uv init                    # 初始化项目
uv sync                    # 同步依赖
uv run <command>           # 运行命令

# 依赖管理
uv add <package>           # 添加依赖
uv remove <package>        # 移除依赖
uv tree                    # 查看依赖树
uv lock                    # 锁定依赖

# Python 版本管理
uv python list             # 列出 Python 版本
uv python install <ver>    # 安装 Python 版本
uv python pin <ver>        # 固定项目 Python 版本

# 环境管理
uv venv                    # 创建虚拟环境
uv cache clean             # 清理缓存

11.2 uvx 常用命令

# 代码质量工具
uvx black .                # 代码格式化
uvx isort .                # 导入排序
uvx flake8 .               # 代码检查
uvx mypy .                 # 类型检查

# 开发工具
uvx jupyter lab            # 启动 Jupyter Lab
uvx pytest                # 运行测试
uvx sphinx-build           # 构建文档

# 包管理
uvx build                  # 构建包
uvx twine upload           # 上传包

十二、总结

uv 和 uvx 提供了现代化的 Python 项目管理解决方案：

uv 适用于项目开发、依赖管理、环境管理
uvx 适用于运行开发工具、临时工具使用
两者结合使用可以覆盖 Python 开发的全流程
相比传统工具，提供了更快的速度和更好的用户体验

通过本指南，您可以完全使用 uv/uvx 替代传统的 pip、venv、poetry 等工具，享受现代化 Python 开发的便利。

十三、参考资料

最后更新：2025年7月14日

BITBCI

https://bitbci.github.io/2025/07/14/4-python-kai-fa/uv-he-uvx-xian-dai-hua-python-xiang-mu-guan-li-gong-ju/

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 BITBCI !

Python 开发项目管理工具

本篇

uv 和 uvx：现代化 Python 项目管理工具

2025-07-14 Python 开发

Python 开发项目管理工具

常见的AI模型开发平台

2024-12-10 AI模型

项目开发 AI模型