0 为什么需要虚拟环境？

• 隔离依赖：每个项目可以使用不同版本的依赖包，互不干扰。
• 避免污染全局环境：全局 Python 环境保持干净，减少冲突风险。
• 便于部署：通过导出依赖，方便在其他环境中复现。
• 提高安全性：隔离项目环境，防止恶意代码影响系统。

1 使用官方的venv模块创建

使用 Python 的 venv 模块创建和管理虚拟环境是 Python 开发中的常见方式，以下是详细的操作步骤和说明：

1.1 创建虚拟环境

前提条件

• 确保已安装 Python 3.3 或更高版本（venv 是内置模块）。
• 检查 Python 和 pip 是否可用：

  python --version  # 查看 Python 版本
  pip --version     # 检查 pip 是否可用

  如果未安装 Python，请从 Python 官网 下载并安装。

创建虚拟环境

1. 进入项目目录
   打开终端（Windows 使用命令提示符或 PowerShell，Linux/macOS 使用终端），进入你的项目根目录：

   cd /path/to/your/project

2. 创建虚拟环境
   在项目目录下执行以下命令：

   python -m venv .venv

   • 该命令会在当前目录下生成一个包含独立 Python 运行环境的文件夹。
   • .venv 是生成的虚拟环境文件夹名称（你可以自定义，如 venv、myenv 等，建议使用.venv,因为主流的IDE通常会自动识别到.venv）。

1.2 激活虚拟环境

Windows 系统

# 进入虚拟环境的 Scripts 目录
cd .venv\Scripts

# 激活虚拟环境
activate

激活后，命令行提示符会显示虚拟环境名称（如 (venv)）。

Linux/macOS 系统

# 进入虚拟环境的 bin 目录
cd .venv/bin

# 激活虚拟环境
source activate

激活后，终端提示符会显示虚拟环境名称（如 (venv)）。

1.3 安装依赖包

激活虚拟环境后，使用 pip 安装所需的包，这些包会被安装到虚拟环境的 site-packages 目录中，而不会影响全局 Python 环境。

示例：安装 Django

pip install django

查看已安装的包

pip list

1.4 退出虚拟环境

当需要退出虚拟环境时，只需执行以下命令：

deactivate

命令行提示符会恢复到原始状态，表示已退出虚拟环境。

1.5 配置 IDE（如 VSCode）使用虚拟环境

步骤

1. 打开 VSCode 并加载你的项目目录。
2. 选择虚拟环境的解释器：
   • 按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS）打开命令面板。
   • 输入 Python: Select Interpreter 并选择它。
   • 在列表中选择你的虚拟环境路径（例如 .venv/bin/python 或 .venv\Scripts\python.exe）。
3. 验证配置：
   • VSCode 的终端会自动激活虚拟环境，提示符前会显示虚拟环境名称（如 (.venv)）。
   • 可以通过以下命令验证 Python 解释器路径：

     which python  # Linux/macOS
     where python  # Windows

自动激活虚拟环境（可选）

在 VSCode 的项目根目录下创建 .vscode/settings.json 文件，添加以下内容：

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.terminal.activateEnvironment": true
}

这样每次打开项目时，VSCode 会自动激活虚拟环境。

1.6 删除虚拟环境

如果不再需要某个虚拟环境，直接删除其文件夹即可：

# Windows
rmdir /s /q .venv

# Linux/macOS
rm -rf .venv

1.7 常见问题及解决方案

问题 1：激活脚本权限不足（Windows）

• 现象：运行 activate 时提示权限错误。
• 解决方法：
  • 以管理员身份运行 PowerShell。
  • 执行以下命令更改执行策略：

    Set-ExecutionPolicy Bypass -Scope CurrentUser

问题 2：虚拟环境路径错误

• 现象：找不到 activate 脚本。
• 解决方法：
  • 确保进入虚拟环境的 Scripts（Windows）或 bin（Linux/macOS）目录后再执行激活命令。

问题 3：如何指定 Python 版本？

• 需求：如果你安装了多个 Python 版本，可以指定使用特定版本创建虚拟环境。
• 示例：

  # 使用 Python 3.8 创建虚拟环境
  python3.8 -m venv .venv

总结流程

1. 创建虚拟环境：python -m venv .venv
2. 激活虚拟环境：source .venv/bin/activate（Linux/macOS）或 .venv\Scripts\activate（Windows）。
3. 安装依赖：pip install <package>
4. 退出虚拟环境：deactivate
5. 删除虚拟环境：删除 .venv 文件夹。

2 使用Conda创建虚拟环境

2.1 安装 Conda（推荐 Miniconda）

如果尚未安装 Conda，请先安装 Miniconda（轻量版）或 Anaconda（集成版）：

• Miniconda：下载地址
• Anaconda：下载地址

安装完成后，验证安装是否成功：

conda --version

输出类似 conda 24.11.1 表示安装成功。

2.2 创建虚拟环境

基本语法

conda create -n <环境名称> [python=<版本号>]

• <环境名称>：自定义环境名称（如 myenv）。
• python=<版本号>：可选参数，指定 Python 版本（如 python=3.9）。

示例

• 创建一个名为 fastdeploy 的环境，并指定 Python 3.10：

  conda create -n fastdeploy python=3.10

• 创建不指定 Python 版本的环境：

  conda create -n myenv

指定安装路径（可选）

conda create --prefix ./envs/fastdeploy python=3.10

将环境安装到当前目录下的 envs/fastdeploy 文件夹中。

2.3 激活虚拟环境

创建环境后，需要激活它才能使用：

conda activate <环境名称>

• 示例：

  conda activate fastdeploy

  激活后，终端提示符前会显示环境名称（如 (fastdeploy)）。

2.4 安装包

激活环境后，可以安装所需的包：

使用 Conda 安装

conda install <包名>

• 示例：安装 numpy 和 pandas：

  conda install numpy pandas

使用 Pip 安装

如果某些包无法通过 Conda 安装，可以使用 pip：

pip install <包名>

• 示例：安装 requests：

  pip install requests

2.5 查看已安装的包

• 查看当前环境的包列表：

  conda list

• 查看其他环境的包列表：

  conda list -n <环境名称>

2.6 退出虚拟环境

使用以下命令退出当前环境：

conda deactivate

2.7 查看所有虚拟环境

列出所有已创建的环境：

conda env list

输出示例：

# conda environments:
#
base                  *  /home/user/miniconda3
fastdeploy               /home/user/miniconda3/envs/fastdeploy
myenv                    /home/user/miniconda3/envs/myenv

2.8 删除虚拟环境

删除不再需要的环境：

conda remove -n <环境名称> --all

• 示例：删除 fastdeploy 环境：

  conda remove -n fastdeploy --all

2.9 导出和导入环境

导出环境配置

将环境配置保存为 environment.yaml 文件：

conda env export > environment.yaml

根据 YAML 文件创建环境

使用导出的配置文件创建新环境：

conda env create -f environment.yaml

2.10 常见问题及解决方法

问题 1：无法激活环境

• 错误提示：CondaError: Run 'conda init' before 'conda activate'
• 解决方法：
  1. 以管理员身份运行终端。
  2. 执行命令：

     conda init

  3. 关闭并重新打开终端。

问题 2：安装包时卡顿或速度慢

• 解决方法：更换为国内镜像源（如清华大学镜像）：

  conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
  conda config --set show_channel_urls yes

问题 3：依赖冲突

• 解决方法：
  1. 清除 Conda 缓存：

     conda clean --all

  2. 更新 Conda 到最新版本：

     conda update conda

总结

1. 创建环境：conda create -n <name> python=<version>
2. 激活环境：conda activate <name>
3. 安装包：conda install <package> 或 pip install <package>
4. 退出环境：conda deactivate
5. 删除环境：conda remove -n <name> --all

3 使用uv创建虚拟环境

以下是使用 uv 创建和管理虚拟环境的详细指南，涵盖安装、环境创建、依赖管理和常见操作：

3.1 安装 uv

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

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

# With pip.
pip install uv

验证安装

uv --version

输出类似 uv 0.1.1 表示安装成功。

3.2 创建虚拟环境

基本语法

uv venv [选项]

常用示例

1. 默认创建虚拟环境
   在当前目录下生成 .venv 文件夹：

   uv venv

2. 指定虚拟环境名称和路径
   创建名为 myenv 的环境：

   uv venv myenv

3. 指定 Python 版本
   创建使用 Python 3.11 的环境：

   uv venv --python 3.11

4. 同时指定名称和 Python 版本

   uv venv myenv --python 3.11

---

3.3 激活虚拟环境

Linux/macOS

source .venv/bin/activate

Windows（CMD）

.venv\Scripts\activate.bat

Windows（PowerShell）

.venv\Scripts\Activate.ps1

Git Bash（Windows）

source .venv/Scripts/activate

激活后，终端提示符会显示环境名称（如 (myenv)）。

---

3.4 安装依赖包

uv 提供了更现代、更简洁的 add 命令来替代传统的 pip install，这是它作为现代 Python 工具链一员的重要特性。

---

为什么使用 uv add？

uv 不仅仅是一个虚拟环境管理工具，它还内置了一个项目依赖管理器（类似于 poetry 或 pipenv）。在这种模式下：

• uv add: 将包添加到项目依赖中，并自动更新 pyproject.toml 文件。
• uv pip install: 仅安装包，不修改项目配置文件，更接近传统 pip 的行为。

---

使用 uv add 管理依赖

1. 初始化项目（创建 pyproject.toml）

在使用 add 之前，您需要一个项目配置文件。可以通过 uv init 创建：

uv init my-project
cd my-project

# 如果要指定python版本
uv init <项目名称> --python <版本号>

这会生成一个基础的 pyproject.toml 文件。

2. 安装依赖包

使用 uv add 命令安装包，它会自动将包添加到 pyproject.toml 的 [project.dependencies] 部分。

# 安装主依赖
uv add requests
uv add numpy pandas matplotlib

# 安装开发依赖 (会添加到 [project.optional-dependencies.dev])
uv add pytest black flake8 --dev

# 安装特定版本的包
uv add requests==2.31.0
uv add "django>=4.0,<5.0"

# 从 Git 仓库安装
uv add git+https://github.com/psf/requests.git
uv add git+https://github.com/psf/requests.git@main

执行 uv add 后，pyproject.toml 会自动更新，例如：

[project]
dependencies = [
    "requests==2.31.0",
    "numpy>=1.21.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
]

3. 同步环境

add 命令会修改 pyproject.toml，但实际的安装和环境同步是通过 uv sync 完成的。

# 根据 pyproject.toml 和 uv.lock (如果存在) 安装所有依赖
uv sync

# 只安装主依赖
uv sync --group=dev

# 只安装开发依赖
uv sync --group=dev

最佳实践：

1. 使用 uv add 添加新包（修改 pyproject.toml）。
2. 使用 uv sync 应用更改（安装/更新包到虚拟环境）。

4. 移除依赖包

# 移除主依赖
uv remove requests

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

这会自动从 pyproject.toml 中移除对应的包。

5. 查看项目依赖

# 查看 pyproject.toml 中声明的依赖
uv project show

# 查看环境中实际安装的包
uv pip list

6. 导出 requirements.txt

虽然 pyproject.toml 是首选，但您仍然可以导出传统格式：

uv pip freeze > requirements.txt

---

uv add vs uv pip install 总结

特性	uv add	uv pip install
修改 pyproject.toml	✅ 是	❌ 否
项目依赖管理	✅ 是 (现代方式)	❌ 否 (传统方式)
需要 pyproject.toml	✅ 是	❌ 否
典型用途	新项目开发，管理项目依赖	快速安装工具，脚本环境，或已有 requirements.txt 的项目
后续同步	需要 uv sync	立即生效

---

推荐工作流

对于一个新项目，推荐使用 uv add 的完整流程：

# 1. 创建并进入项目目录
mkdir my-awesome-project && cd my-awesome-project

# 2. 初始化项目
uv init

# 3. 创建虚拟环境 (uv init 通常会自动创建 .venv)
# 如果没有，手动创建: uv venv

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

# 5. 使用 add 添加依赖
uv add requests fastapi
uv add pytest --dev

# 6. 同步环境 (安装包)
uv sync

# 7. 开发代码...
# 8. 提交代码 (包含 pyproject.toml 和 uv.lock)

通过使用 uv add 和 uv sync，您可以实现声明式依赖管理，使项目更易于协作和复现。

3.5 管理 Python 版本

查看可用 Python 版本

uv python list

• 蓝色表示已安装的版本，灰色表示可下载的版本。

安装指定 Python 版本

uv python install 3.11

切换当前环境的 Python 版本

uv python pin 3.11

查看当前环境的 Python 版本

uv python pin

---

3.6 运行脚本

直接运行脚本

uv run main.py

这会自动使用当前虚拟环境的 Python 解释器。

指定 Python 版本运行

uv run --python 3.11 main.py

---

3.7 项目初始化

创建项目模板

uv init my-project

生成的文件包括：

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

同步环境和依赖

uv sync

此命令会：

1. 创建虚拟环境
2. 安装 pyproject.toml 中声明的依赖
3. 生成锁定文件 uv.lock

---

3.8 常见问题及解决方法

问题 1：PowerShell 激活脚本被阻止

• 解决方法：修改执行策略

  Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser

问题 2：找不到 Python 版本

• 解决方法：先安装所需版本

  uv python install 3.11

问题 3：依赖冲突

• 解决方法：
  1. 清除缓存：

     uv cache clear

  2. 更新 uv：

     uv self update

---

3.9 与 IDE 集成（以 PyCharm 为例）

1. 打开项目目录：使用 PyCharm 打开项目文件夹。
2. 选择虚拟环境：
   • 点击 File > Settings > Project: <项目名> > Python Interpreter。
   • 点击齿轮图标，选择 Add...。
   • 选择 Existing environment，然后找到 .venv/bin/python（Linux/macOS）或 .venv\Scripts\python.exe（Windows）。
3. 验证配置：终端激活虚拟环境后运行 which python 或 where python 应指向 .venv 路径。

---

3.10 uv 与传统工具的对比

功能	uv	venv	Conda
创建环境速度	极快（优化了路径和依赖管理）	一般	较慢（需要下载包）
Python 版本管理	支持安装和切换任意版本	依赖系统已安装的 Python	支持多种语言版本
依赖管理	内置 pip 兼容命令	依赖 pip	内置包管理器
跨平台支持	是	是	是
适用场景	快速开发、轻量级项目	通用 Python 项目	数据科学、跨语言项目

---

总结

1. 安装 uv：按操作系统选择命令。
2. 创建环境：uv venv [选项]。
3. 激活环境：source .venv/bin/activate（Linux/macOS）或 .venv\Scripts\activate（Windows）。
4. 安装依赖：uv add <包名>。
5. 运行脚本：uv run <脚本名>。
6. 管理 Python 版本：uv python install <版本> 和 uv python pin <版本>。