pip 和uv 开发和部署python项目

以下是使用 pip 和 uv 管理 Python 项目依赖的完整对比指南，涵盖从项目初始化到部署的全流程：

一、使用 pip + venv（传统方式）

1. 项目初始化

bash 复制代码

# 创建项目目录
mkdir my_project && cd my_project

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

2. 安装依赖

bash 复制代码

# 安装包
pip install requests flask

# 查看所有已安装的包
pip list

3. 导出依赖清单

bash 复制代码

# 生成 requirements.txt（仅导出当前虚拟环境中的包）
pip freeze > requirements.txt

生成的 requirements.txt 内容示例：

复制代码

requests==2.31.0
flask==3.0.0
werkzeug==3.0.1
...

4. 部署时还原环境

在目标机器上：

bash 复制代码

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS

# 一键安装所有依赖
pip install -r requirements.txt

# 运行项目
python main.py

5. 注意事项

.venv/ 目录必须加入 .gitignore，不要提交到 Git
只提交 requirements.txt 和源代码
如果需要更严格的版本锁定，可配合 pip-tools 使用 pip-compile 生成带 hash 的锁文件

二、使用 uv（现代方式）

uv 是用 Rust 编写的极速 Python 包管理工具，可以替代 pip + venv + pip-tools 的组合。

1. 安装 uv

bash 复制代码

# 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"

# 验证安装
uv --version

2. 项目初始化

bash 复制代码

# 创建项目目录并初始化（自动生成 pyproject.toml）
mkdir my_project && cd my_project
uv init

# 创建虚拟环境（可选，uv 会自动管理）
uv venv --python 3.12

3. 添加依赖

bash 复制代码

# 添加运行时依赖（自动更新 pyproject.toml 和 uv.lock）
uv add requests flask

# 添加开发依赖（测试、lint 等，生产环境不安装）
uv add --dev pytest black

4. 锁定与同步

bash 复制代码

# 解析依赖并生成/更新 uv.lock（不安装包）
uv lock

# 严格按锁文件安装所有依赖（自动创建 .venv）
uv sync

5. 运行项目

bash 复制代码

# 无需手动激活虚拟环境，uv 自动识别
uv run python main.py

# 或直接运行框架命令
uv run flask --app app run

6. 部署时还原环境

在目标机器上：

bash 复制代码

# 只需传输 pyproject.toml、uv.lock 和源代码（不传 .venv）

# 一键同步环境（自动创建 .venv 并安装所有依赖）
uv sync

# 生产环境只装运行依赖，排除开发依赖
uv sync --no-dev

# CI/CD 中严格按锁文件安装（不重新解析）
uv sync --frozen

# 运行项目
uv run python main.py

三、核心对比

对比项	pip + venv	uv
安装速度	较慢（Python 编写）	极快（Rust 编写）
配置文件	`requirements.txt`	`pyproject.toml` + `uv.lock`
版本锁定	需手动 `pip freeze` 或借助 `pip-tools`	原生支持，`uv lock` 自动生成
虚拟环境管理	手动 `python -m venv`	`uv venv` 自动管理
开发依赖区分	需手动维护多个 txt 文件	`uv add --dev` 原生支持
运行命令	需先 `activate` 再 `python`	`uv run` 自动识别环境
依赖树查看	`pip list`（扁平列表）	`uv tree`（层级展示）
Git 提交内容	源代码 + `requirements.txt`	源代码 + `pyproject.toml` + `uv.lock`
离线部署	需 `pip download` 预下载包	支持 `--offline` 模式

四、从 pip 迁移到 uv

如果你已有 requirements.txt，可以低成本迁移：

bash 复制代码

# 方式一：继续使用 requirements.txt（最小改动）
uv venv
uv pip sync requirements.txt    # 比 pip install -r 更严格，会移除多余包

# 方式二：升级为 uv 项目工作流（推荐）
uv init                         # 生成 pyproject.toml
uv add -r requirements.txt      # 将现有依赖导入
uv lock                         # 生成锁文件
uv sync                         # 同步环境

五、uv 项目推荐的 .gitignore 模板

以下是 uv 项目推荐的 .gitignore 模板，覆盖了虚拟环境、缓存、IDE 配置等常见需要忽略的内容：

gitignore 复制代码

# ==================== 虚拟环境 ====================
# Python 虚拟环境（uv 默认创建在 .venv）
.venv/
venv/
env/
ENV/

# uv 管理的虚拟环境符号链接
.python-version

# ==================== Python 缓存 ====================
# 字节码缓存
__pycache__/
*.pyc
*.pyo
*.pyd
*.pyi

# pytest 缓存
.pytest_cache/
.coverage
htmlcov/
.tox/
.nox/

# mypy 缓存
.mypy_cache/
.dmypy.json
dmypy.json

# ==================== uv 相关 ====================
# uv 缓存目录（通常不在项目内，但以防万一）
.uv-cache/

# ==================== IDE 配置 ====================
# VS Code
.vscode/
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
*.code-workspace

# PyCharm
.idea/
*.iml
*.iws
*.ipr

# Jupyter Notebook
.ipynb_checkpoints/

# ==================== 操作系统 ====================
# macOS
.DS_Store
.AppleDouble
.LSOverride
._*

# Windows
Thumbs.db
Thumbs.db:encryptable
ehthumbs.db
ehthumbs_vista.db
*.stackdump
[Dd]esktop.ini
$RECYCLE.BIN/
*.cab
*.msi
*.msix
*.msm
*.msp
*.lnk

# Linux
*~
.fuse_hidden*
.directory
.Trash-*

# ==================== 临时文件 ====================
# 编辑器临时文件
*.swp
*.swo
*~
*.bak
*.tmp
*.temp

# 日志文件
*.log

# 环境变量（可能包含密钥）
.env
.env.local
.env.*.local

# ==================== 构建产物 ====================
# 打包产物
dist/
build/
*.egg-info/
*.egg
*.whl

# Hatch 构建目录
.hatch/

# ==================== 数据文件（按需取消注释）====================
# 如果项目中有大型数据文件，建议用 Git LFS 管理
# data/*.csv
# data/*.json
# models/*.pkl
# models/*.h5

几点说明

.venv/ 必须忽略：这是核心，防止虚拟环境被提交到 Git。
.python-version ：如果你用 pyenv 管理 Python 版本，这个文件记录了项目所需的 Python 版本，可以提交；如果只是 uv 自动创建的，建议忽略。
.env 文件 ：环境变量文件通常包含数据库密码、API 密钥等敏感信息，必须忽略。建议在项目中放一个 .env.example 作为模板提交。
dist/ 和 build/ ：如果你用 uv build 打包项目，这些目录是构建产物，不需要提交。
按需调整 ：如果你的项目没有用到 Jupyter、myPy、tox 等工具，可以删除对应的段落，保持 .gitignore 简洁。

快速创建

在项目根目录执行：

bash 复制代码

curl -o .gitignore https://raw.githubusercontent.com/astral-sh/uv/main/.gitignore

或者直接复制上面的内容保存为 .gitignore 文件。

六、总结建议

个人小项目 / 快速原型：pip + venv 足够，简单直接
团队协作 / 生产部署 / 频繁重建环境：强烈推荐 uv，速度快、锁文件可靠、工作流更规范
无论用哪种方式 ：永远不要将 .venv/ 提交到 Git，只提交依赖清单文件（requirements.txt 或 pyproject.toml + uv.lock）