使用uv管理Python包：实例

使用 uv 管理多个虚拟环境（venv）时，可以做到 快速、高效、干净地切换项目环境。

---

🎯 一、最佳实践：每个项目一个虚拟环境

建议把虚拟环境放在项目目录内或统一放在一个专用目录，比如：

• 项目目录下的 .venv/
• 统一放到 ~/.venvs/<项目名>/

---

🚀 二、uv 管理多个 venv 的基本命令

✅ 创建虚拟环境

uv venv         # 在当前目录创建 .venv
uv venv path/to/env  # 自定义路径

默认会在当前目录创建 .venv，并写入 .venv 文件（方便编辑器识别，比如 VS Code）。

---

✅ 激活虚拟环境

source .venv/bin/activate      # macOS/Linux
.venv\Scripts\activate         # Windows

✅ 安装依赖（像 pip 一样用）

uv pip install requests

---

📁 三、项目结构推荐（可管理多个 venv）

my-project/
├── .venv/              # uv 创建的虚拟环境
├── pyproject.toml      # 项目依赖（推荐用）
├── requirements.txt    # 可选
└── src/                # 你的代码

多个项目：

~/.venvs/
├── projA/
│   └── .venv/
├── projB/
│   └── .venv/

---

📘 四、进阶建议

1. 用 direnv + uv 实现自动激活

# .envrc 文件内容
source .venv/bin/activate

然后在项目目录运行：

direnv allow

离开项目目录会自动停用虚拟环境。

---

2. 让 VS Code 自动识别 .venv

在 .vscode/settings.json 中写入：

{
  "python.pythonPath": ".venv/bin/python"
}

---

3. 使用 uv pip sync 保持一致性

uv pip freeze > requirements.txt    # 导出依赖
uv pip sync requirements.txt        # 完全同步依赖，防止包冲突

---

🛑 五、注意事项

注意点	说明
虚拟环境路径建议统一	便于自动工具识别（如 .venv/）
不要手动改 .venv 中的内容	用 uv pip 安装/卸载包即可
用 uv pip sync 替代 pip install	更干净、更确定（适合 CI 和团队合作）
pyproject.toml 支持更好	推荐使用 uv pip compile 搭配 pyproject.toml 管理依赖

---

🧪 示例：从零创建新项目并用 uv 管理

mkdir myapp && cd myapp
uv venv
source .venv/bin/activate
uv pip install requests fastapi
uv pip freeze > requirements.txt

你现在有一个干净、可复现、可分享的项目环境了 🎉

---

下面是一个完整的 Bash 脚本，可以：

1. 创建项目目录（可传参）
2. 创建并激活 uv 虚拟环境
3. 初始化 requirements.txt 和 .gitignore
4. 设置 direnv 的自动激活（写入 .envrc）

---

📜 脚本内容：init-uv-project.sh

#!/bin/bash

# 获取项目名参数（默认当前目录）
PROJECT_NAME=${1:-myproject}
PROJECT_PATH=$(realpath "$PROJECT_NAME")

# 创建项目目录
mkdir -p "$PROJECT_PATH"
cd "$PROJECT_PATH" || exit

# 初始化虚拟环境
echo "🔧 Creating uv virtual environment in $PROJECT_PATH"
uv venv .venv || { echo "❌ uv not installed or failed to create venv."; exit 1; }

# 激活虚拟环境（当前 shell）
echo "✅ Virtual environment created at .venv"
source .venv/bin/activate

# 创建空 requirements.txt
touch requirements.txt

# 创建 .gitignore 文件
cat <<EOF > .gitignore
.venv/
__pycache__/
*.pyc
.envrc
EOF

# 设置 direnv 自动激活
echo 'source .venv/bin/activate' > .envrc
direnv allow

# 初始化 pyproject.toml（可选）
cat <<EOF > pyproject.toml
[project]
name = "$PROJECT_NAME"
version = "0.1.0"
description = ""
dependencies = []
EOF

# 提示完成
echo "🎉 Project '$PROJECT_NAME' is ready!"
echo "💡 You can now run: uv pip install <package>"

---

✅ 使用方法：

1. 保存脚本并赋权

chmod +x init-uv-project.sh

2. 运行脚本（带项目名）

./init-uv-project.sh awesome-app

---

🧠 脚本执行后目录结构如下：

awesome-app/
├── .venv/              # uv 创建的虚拟环境
├── .envrc              # direnv 自动激活配置
├── .gitignore
├── requirements.txt
└── pyproject.toml

---