Python 虚拟环境搭建与包管理完全指南

Python 虚拟环境搭建与包管理完全指南

Someone Lv5
  2026-06-07 07:45 2026-06-07 07:45 创建   2026-06-18 08:39:57 2026-06-18 08:39:57 更新      2.2k 字  9 分钟  

Python 是目前最流行的编程语言之一，从 Web 开发、数据分析到人工智能和自动化运维，Python 的身影无处不在。然而，Python 生态中的依赖管理和环境隔离一直是初学者最容易踩坑的地方。本文将系统性地介绍 Python 虚拟环境搭建与包管理的各种方案和最佳实践。

一、为什么需要虚拟环境？

Python 的全局包目录 (site-packages) 是所有项目共享的，这会带来几个严重问题：

1
2
3
4
5
6
项目 A 依赖 Django 3.2（旧版本兼容）
项目 B 依赖 Django 5.1（最新特性）
→ 全局只能安装一个版本，冲突！

系统包管理器需要特定版本
→ 随意升级可能导致系统工具崩溃

虚拟环境为每个项目创建独立的 Python 解释器和包目录，从根本上解决了依赖冲突问题。

二、Python 版本管理工具

在搭建虚拟环境之前，首先需要管理 Python 本身的多版本共存。

pyenv — Python 版本管理利器

pyenv 可以在系统上同时安装多个 Python 版本，并随时切换。

Linux / macOS 安装：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 安装依赖
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# 安装 pyenv
curl https://pyenv.run | bash

# 将以下内容添加到 ~/.bashrc 或 ~/.zshrc
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Windows 安装：

Windows 上推荐使用 pyenv-win：

1
2
3
4
5
6
# PowerShell（管理员）
Invoke-WebRequest -Uri https://pyenv.run -OutFile "$env:TEMP\pyenv-install.ps1"
& "$env:TEMP\pyenv-install.ps1"

# 或使用 scoop
scoop install pyenv

常用命令：

1
2
3
4
5
pyenv install --list         # 列出可安装版本
pyenv install 3.12.0         # 安装指定版本
pyenv versions               # 列出已安装版本
pyenv global 3.12.0          # 设置全局版本
pyenv local 3.10.0           # 为当前目录设置版本（生成 .python-version 文件）

三、虚拟环境创建方案

方案一：venv（官方推荐，Python ≥ 3.3）

venv 是 Python 标准库自带的虚拟环境工具，无需额外安装。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 创建虚拟环境
python3 -m venv myproject-venv

# 指定 Python 版本创建
python3.12 -m venv myproject-venv

# 激活虚拟环境（Linux / macOS）
source myproject-venv/bin/activate

# 激活虚拟环境（Windows PowerShell）
myproject-venv\Scripts\Activate.ps1

# 激活虚拟环境（Windows CMD）
myproject-venv\Scripts\activate.bat

# 退出虚拟环境
deactivate

激活后，终端提示符前面会出现 (myproject-venv) 标识，表示当前在虚拟环境中。

优点： 零依赖、Python 内置、简单轻量
缺点： 功能较基础，不支持 Python 2，无法跨 Python 大版本

方案二：virtualenv（第三方，功能更强大）

virtualenv 是 venv 的前身和功能增强版，支持 Python 2 和 3，且创建速度更快。

1
2
3
4
5
6
7
8
9
10
11
# 安装
pip install virtualenv

# 创建虚拟环境
virtualenv myproject-venv

# 指定 Python 版本
virtualenv -p python3.12 myproject-venv

# 创建纯净环境（不安装 pip 等）
virtualenv --no-pip --no-setuptools --no-wheel myproject-venv

优点： 兼容性更好、创建速度快、支持 Python 2
缺点： 需要额外安装

方案三：conda（数据科学首选）

Anaconda / Miniconda 自带环境管理功能，特别适合数据科学和机器学习项目。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 安装 Miniconda（推荐，更轻量）
# https://docs.anaconda.com/miniconda/

# 创建环境
conda create -n myproject python=3.12

# 激活环境
conda activate myproject

# 从 environment.yml 创建
conda env create -f environment.yml

# 退出环境
conda deactivate

# 列出所有环境
conda env list

# 删除环境
conda env remove -n myproject

environment.yml 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
name: myproject
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.12
  - numpy=1.26
  - pandas=2.2
  - scikit-learn=1.5
  - pip
  - pip:
    - django==5.1
    - celery==5.4

优点： 支持非 Python 依赖（如 CUDA、OpenCV）、二进制包管理、数据科学生态完善
缺点： 安装包体积大、环境初始化较慢

四、包管理工具进阶

pip — Python 包管理基石

pip 是 Python 最基础的包管理工具，几乎所有方案都依赖它。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 安装包
pip install requests

# 安装指定版本
pip install django==5.1.0

# 安装兼容版本
pip install "django>=4.2,<5.2"

# 从 requirements.txt 安装
pip install -r requirements.txt

# 导出已安装包列表
pip freeze > requirements.txt

# 更精确的导出（推荐）
pip list --format=freeze > requirements.txt

生成需求文件的最佳实践：

1
2
3
4
5
6
7
8
# 只导出显式安装的包（需要 pip-tools）
pip install pip-tools
pip-compile requirements.in

# requirements.in 文件内容
django
celery
redis

pip-compile 会生成包含所有传递依赖的锁定文件 requirements.txt。

Pipenv — 项目化的依赖管理

Pipenv 将 pip 和 virtualenv 合二为一，并用 Pipfile 替代 requirements.txt。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 安装
pip install pipenv

# 为项目创建虚拟环境
pipenv install django

# 安装开发依赖
pipenv install --dev pytest black

# 激活环境（进入子 shell）
pipenv shell

# 直接运行命令
pipenv run python manage.py runserver

# 生成锁定文件
pipenv lock

# 安装锁定版本
pipenv sync

# 显示依赖图
pipenv graph

Poetry — 现代 Python 包管理和打包工具

Poetry 是目前社区最推荐的现代 Python 项目管理工具，集依赖管理、虚拟环境和包发布于一体。

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
# 安装（官方推荐方式）
curl -sSL https://install.python-poetry.org | python3 -

# Windows PowerShell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# 新建项目
poetry new myproject
cd myproject

# 或在已有项目中初始化
poetry init

# 添加依赖
poetry add django
poetry add --dev pytest black mypy

# 安装所有依赖
poetry install

# 激活虚拟环境
poetry shell

# 运行命令
poetry run python main.py

# 构建和发布
poetry build
poetry publish

pyproject.toml 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "一个 Python Web 项目"
authors = ["Your Name <email@example.com>"]

[tool.poetry.dependencies]
python = "^3.12"
django = "^5.1"
celery = "^5.4"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
ruff = "^0.5"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

五、方案对比与选择建议

特性venvvirtualenvcondaPipenvPoetry
需要额外安装否（内置）是是是是
Python 版本管理否否是否否
依赖锁定手动手动❌ conda env exportPipfile.lockpoetry.lock
解析依赖树否否是是是
包发布否否anaconda.org否PyPI
非 Python 依赖否否是否否
适合场景简单项目需要 Python 2数据科学/ML中小型项目中大型项目/库开发

推荐选择策略：

  • 初学者 / 简单脚本 → python3 -m venv + pip + requirements.txt
  • 数据科学 / 机器学习 → conda + environment.yml
  • 中型 Web 项目 → Poetry（现代、完整、易用）
  • 需要严格版本锁定 → Pipenv 或 Poetry

六、最佳实践与常见问题

.gitignore 配置

虚拟环境目录不应提交到 Git 仓库：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 虚拟环境
venv/
.venv/
env/
myproject-venv/

# pyenv
.python-version

# pipenv
.pipenv/

# conda
conda-env/

# Poetry
.poetry/

requirements.txt 生成规范

1
2
3
4
5
# 生产依赖
pip freeze | grep -v "pytest\|black\|mypy\|ruff" > requirements.txt

# 开发依赖（推荐用多个文件）
pip freeze > requirements-dev.txt

常见问题排查

问题 1：pip 安装慢

1
2
3
4
5
# 使用国内镜像源（临时）
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 配置永久镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

问题 2：pip freeze 输出太多包

1
2
3
4
# 使用 pip-tools 只保留顶层依赖
pip install pip-tools
echo "django" > requirements.in
pip-compile requirements.in

问题 3：虚拟环境中找不到已安装的命令

1
2
3
4
5
6
# 检查 PATH 是否正确
echo $PATH
which python

# 常见原因：未在虚拟环境中或环境已损坏
# 解决：重新激活或重新创建环境

问题 4：Windows 上 PowerShell 执行策略限制

1
2
3
4
# 以管理员身份运行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 然后再激活虚拟环境
.venv\Scripts\Activate.ps1

推荐的项目目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
myproject/
├── .venv/                  # 虚拟环境（不提交 Git）
├── .python-version        # pyenv 版本文件
├── pyproject.toml         # 项目配置（Poetry 或 PEP 621）
├── poetry.lock            # Poetry 依赖锁
├── requirements.txt       # pip 依赖文件（可选）
├── README.md
├── src/
│   └── myproject/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
└── .gitignore

七、小结

选择合适的 Python 环境管理方案，能让日常开发事半功倍：

  1. 新手入门：从 venv + pip 开始，理解虚拟环境的本质
  2. 日常项目：尝试 Poetry，体验现代包管理的工作流
  3. 数据科学：掌握 conda，充分利用其二进制包和非 Python 依赖管理能力
  4. 团队协作：统一使用 pyproject.toml（PEP 621 标准），确保环境可复现

Python 虚拟环境本身并不复杂，关键在于养成良好的习惯——每个项目使用独立环境、锁定依赖版本、保持环境文件可复现。掌握了这些基础，就能避免”在我电脑上能跑”的尴尬了。

本文由AI辅助生成，内容仅供参考

  • 标题: Python 虚拟环境搭建与包管理完全指南
  • 作者: Someone
  • 创建于 : 2026-06-07 07:45:00
  • 更新于 : 2026-06-18 08:39:57
  • 链接: https://demo-blog.qusite.cn/2026-06-07-python-venv-guide/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
推荐阅读
Linux crontab 定时任务配置完全指南：从入门到精通 Linux crontab 定时任务配置完全指南：从入门到精通 Java 开发环境搭建完全指南 Java 开发环境搭建完全指南 Ansible 自动化运维配置完全指南 Ansible 自动化运维配置完全指南
推荐阅读
Linux crontab 定时任务配置完全指南：从入门到精通 Linux crontab 定时任务配置完全指南：从入门到精通 Java 开发环境搭建完全指南 Java 开发环境搭建完全指南
目录
Python 虚拟环境搭建与包管理完全指南
  1. 一、为什么需要虚拟环境？
  2. 二、Python 版本管理工具
    1. pyenv — Python 版本管理利器
  3. 三、虚拟环境创建方案
    1. 方案一：venv（官方推荐，Python ≥ 3.3）
    2. 方案二：virtualenv（第三方，功能更强大）
    3. 方案三：conda（数据科学首选）
  4. 四、包管理工具进阶
    1. pip — Python 包管理基石
    2. Pipenv — 项目化的依赖管理
    3. Poetry — 现代 Python 包管理和打包工具
  5. 五、方案对比与选择建议
  6. 六、最佳实践与常见问题
    1. .gitignore 配置
    2. requirements.txt 生成规范
    3. 常见问题排查
    4. 推荐的项目目录结构
  7. 七、小结