name: python-venv-manager description: Python虚拟环境管理、依赖处理和项目设置自动化。

Python虚拟环境管理器技能

Python虚拟环境管理、依赖处理和项目设置自动化。

使用说明

您是一位Python环境和依赖专家。当被调用时：

虚拟环境管理：
- 创建和配置虚拟环境
- 使用pyenv管理Python版本
- 设置隔离开发环境
- 处理每个项目的多个Python版本
- 配置环境激活脚本
依赖管理：
- 生成和管理requirements.txt
- 使用现代工具（pip-tools、poetry、pipenv）
- 使用哈希锁定依赖
- 处理开发与生产依赖
- 解决依赖冲突
项目设置：
- 初始化新的Python项目
- 配置项目结构
- 设置测试框架
- 配置代码检查和格式化
- 创建可复现的环境
故障排除：
- 修复导入错误
- 解决版本冲突
- 调试安装问题
- 处理平台特定依赖
- 清理损坏的环境
最佳实践：提供Python打包、版本控制和环境隔离的指导

虚拟环境工具比较

venv（内置）

# 优点：内置，无需安装
# 缺点：功能基础，手动工作流

# 创建环境
python3 -m venv venv

# 激活（Linux/Mac）
source venv/bin/activate

# 激活（Windows）
venv\Scripts\activate

# 停用
deactivate

# 安装依赖
pip install -r requirements.txt

virtualenv（增强版）

# 优点：更多功能，比venv更快
# 缺点：需要安装

# 安装
pip install virtualenv

# 用特定Python版本创建
virtualenv -p python3.11 venv

# 用系统site-packages创建
virtualenv --system-site-packages venv

Poetry（现代，推荐）

# 优点：依赖解析、打包、发布
# 缺点：学习曲线

# 安装
curl -sSL https://install.python-poetry.org | python3 -

# 创建新项目
poetry new my-project

# 初始化现有项目
poetry init

# 添加依赖
poetry add requests
poetry add --group dev pytest

# 安装依赖
poetry install

# 在虚拟环境中运行命令
poetry run python script.py
poetry run pytest

# 激活shell
poetry shell

# 更新依赖
poetry update

# 显示依赖树
poetry show --tree

Pipenv

# 优点：自动虚拟环境，Pipfile格式
# 缺点：比替代方案慢

# 安装
pip install pipenv

# 安装依赖
pipenv install requests

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

# 激活环境
pipenv shell

# 运行命令
pipenv run python script.py

# 生成requirements.txt
pipenv requirements > requirements.txt

pyenv（Python版本管理器）

# 安装多个Python版本
# 管理每个项目的Python版本

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

# 安装Python版本
pyenv install 3.11.5
pyenv install 3.12.0

# 列出可用版本
pyenv install --list

# 设置全局版本
pyenv global 3.11.5

# 设置本地版本（按目录）
pyenv local 3.11.5

# 列出已安装版本
pyenv versions

# 显示当前版本
pyenv version

使用示例

@python-venv-manager
@python-venv-manager --setup-project
@python-venv-manager --create-venv
@python-venv-manager --poetry
@python-venv-manager --fix-dependencies
@python-venv-manager --migrate-to-poetry

项目设置工作流

使用venv的基本项目

# 创建项目目录
mkdir my-project
cd my-project

# 创建虚拟环境
python3 -m venv venv

# 激活环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 升级pip
pip install --upgrade pip

# 安装依赖
pip install requests pytest black flake8

# 冻结依赖
pip freeze > requirements.txt

# 创建.gitignore
cat > .gitignore << EOF
venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.so
*.egg
*.egg-info/
dist/
build/
.pytest_cache/
.coverage
htmlcov/
.env
.venv
EOF

使用Poetry的现代项目

# 创建带结构的新项目
poetry new my-project
cd my-project

# 项目结构创建：
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── my_project/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

# 添加依赖
poetry add requests httpx pydantic
poetry add --group dev pytest pytest-cov black flake8 mypy

# 安装依赖
poetry install

# 配置pyproject.toml
cat >> pyproject.toml << EOF

[tool.black]
line-length = 88
target-version = ['py311']

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
EOF

初始化现有项目

# 导航到项目
cd existing-project

# 初始化poetry
poetry init

# 跟随交互提示，然后添加依赖
poetry add $(cat requirements.txt)

# 添加开发依赖
poetry add --group dev pytest black flake8

# 创建虚拟环境
poetry install

# 验证安装
poetry run python -c "import requests; print(requests.__version__)"

依赖管理

requirements.txt最佳实践

# 基本requirements.txt
requests==2.31.0
django==4.2.7
celery==5.3.4

# 使用哈希提高安全性（pip-tools）
pip-compile --generate-hashes requirements.in

# 分离文件
requirements/
├── base.txt          # 通用依赖
├── development.txt   # 开发依赖
├── production.txt    # 生产依赖
└── testing.txt       # 测试依赖

# development.txt
-r base.txt
pytest==7.4.3
black==23.11.0
flake8==6.1.0

# 从特定文件安装
pip install -r requirements/development.txt

使用pip-tools（推荐）

# 安装pip-tools
pip install pip-tools

# 创建requirements.in
cat > requirements.in << EOF
django>=4.2,<5.0
requests
celery[redis]
EOF

# 编译到带固定版本的requirements.txt
pip-compile requirements.in

# 从编译的requirements安装
pip-sync requirements.txt

# 更新依赖
pip-compile --upgrade requirements.in

# 使用哈希编译以提高安全性
pip-compile --generate-hashes requirements.in

Poetry依赖管理

# 添加带版本约束的依赖
poetry add "django>=4.2,<5.0"

# 添加特定版本
poetry add django@4.2.7

# 从git添加
poetry add git+https://github.com/user/repo.git

# 从本地路径添加
poetry add --editable ./local-package

# 添加带附加功能的依赖
poetry add "celery[redis,auth]"

# 更新特定包
poetry update django

# 更新所有包
poetry update

# 显示过时包
poetry show --outdated

# 移除包
poetry remove requests

# 导出到requirements.txt
poetry export -f requirements.txt --output requirements.txt
poetry export --without-hashes -f requirements.txt --output requirements.txt

开发与生产依赖

# Poetry方法
[tool.poetry.dependencies]
python = "^3.11"
django = "^4.2"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.11"
flake8 = "^6.1"

# 安装时不包含开发依赖
poetry install --without dev

# 仅安装特定组
poetry install --only dev

# pip-tools方法
# requirements.in（生产）
django>=4.2
requests

# requirements-dev.in（开发）
-r requirements.in
pytest>=7.4
black>=23.11
flake8>=6.1

# 编译两者
pip-compile requirements.in
pip-compile requirements-dev.in

Python版本管理

使用pyenv

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

# 添加到shell配置（.bashrc, .zshrc）
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# 安装Python版本
pyenv install 3.11.5
pyenv install 3.12.0

# 设置全局版本
pyenv global 3.11.5

# 设置本地版本（创建.python-version文件）
pyenv local 3.11.5

# 用特定版本创建虚拟环境
pyenv virtualenv 3.11.5 my-project-env

# 激活虚拟环境
pyenv activate my-project-env

# 停用
pyenv deactivate

# 列出虚拟环境
pyenv virtualenvs

# 删除虚拟环境
pyenv uninstall my-project-env

使用pyenv与Poetry

# 设置本地Python版本
pyenv local 3.11.5

# 初始化Poetry项目
poetry init

# Poetry将使用pyenv的Python版本
poetry env use python

# 或显式指定版本
poetry env use 3.11

# 列出Poetry环境
poetry env list

# 移除环境
poetry env remove python3.11

# 显示环境信息
poetry env info

项目结构最佳实践

小型项目

my-project/
├── .gitignore
├── README.md
├── requirements.txt
├── setup.py  （可选）
├── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py

中型项目

my-project/
├── .gitignore
├── README.md
├── pyproject.toml
├── setup.py
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── models.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── docs/
    └── index.md

大型项目（使用Poetry）

my-project/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
├── poetry.lock
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core/
│       │   ├── __init__.py
│       │   └── engine.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   │   └── test_core.py
│   └── integration/
│       └── test_api.py
├── docs/
│   ├── conf.py
│   └── index.rst
└── scripts/
    └── setup_dev.sh

常见问题与解决方案

问题：ModuleNotFoundError

# 检查虚拟环境是否激活
which python  # 应指向venv/bin/python

# 验证包是否已安装
pip list | grep package-name

# 重新安装包
pip install --force-reinstall package-name

# 检查Python路径
python -c "import sys; print('
'.join(sys.path))"

# 修复：激活虚拟环境
source venv/bin/activate

# 修复：以可编辑模式安装本地开发
pip install -e .

问题：依赖冲突

# 检查冲突
pip check

# 显示依赖树
pip install pipdeptree
pipdeptree

# 使用Poetry（更好的冲突解决）
poetry add package-name
# Poetry将自动解决冲突

# 强制特定版本
pip install "package==1.2.3"

# 使用pip-tools解决
pip-compile --resolver=backtracking requirements.in

问题：多个Python版本混淆

# 检查当前Python版本
python --version
which python

# 显式使用特定版本
python3.11 -m venv venv

# 使用pyenv
pyenv versions  # 列出已安装版本
pyenv which python  # 显示当前Python路径

# 为项目设置特定版本
pyenv local 3.11.5

问题：损坏的虚拟环境

# 删除并重新创建
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 使用Poetry
poetry env remove python3.11
poetry install

问题：SSL证书错误

# 临时解决方案（不适用于生产）
pip install --trusted-host pypi.org --trusted-host pypi.python.org package-name

# 更好的解决方案：更新证书
pip install --upgrade certifi

# macOS特定
/Applications/Python\ 3.11/Install\ Certificates.command

问题：权限拒绝

# 不要在虚拟环境中使用sudo和pip！
# 用正确权限重新创建venv

# 修复所有权
chown -R $USER:$USER venv/

# 如果不在venv中，仅使用用户安装
pip install --user package-name

环境变量和配置

.env文件

# 安装python-decouple或python-dotenv
poetry add python-dotenv

# 创建.env文件
cat > .env << EOF
DEBUG=True
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@localhost/db
REDIS_URL=redis://localhost:6379
EOF

# 在Python中加载
from dotenv import load_dotenv
import os

load_dotenv()

DEBUG = os.getenv('DEBUG', 'False') == 'True'
SECRET_KEY = os.getenv('SECRET_KEY')
DATABASE_URL = os.getenv('DATABASE_URL')

环境特定设置

# config.py
import os
from pathlib import Path

class Config:
    BASE_DIR = Path(__file__).parent
    SECRET_KEY = os.getenv('SECRET_KEY')
    DEBUG = False
    TESTING = False

class DevelopmentConfig(Config):
    DEBUG = True
    DATABASE_URL = 'sqlite:///dev.db'

class ProductionConfig(Config):
    DATABASE_URL = os.getenv('DATABASE_URL')

class TestingConfig(Config):
    TESTING = True
    DATABASE_URL = 'sqlite:///test.db'

# 基于环境选择配置
config = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'testing': TestingConfig,
    'default': DevelopmentConfig
}

def get_config():
    env = os.getenv('FLASK_ENV', 'default')
    return config[env]()

测试设置

pytest配置

# 安装pytest
poetry add --group dev pytest pytest-cov pytest-mock

# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = "-v --tb=short --strict-markers"

# 运行测试
poetry run pytest

# 使用覆盖率
poetry run pytest --cov=src --cov-report=html

# 运行特定测试
poetry run pytest tests/test_core.py::test_function_name

代码质量工具

格式化和代码检查

# 安装工具
poetry add --group dev black isort flake8 mypy pylint

# pyproject.toml配置
[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'
extend-exclude = '''
/(
  # 目录
  \.eggs
  | \.git
  | \.venv
  | build
  | dist
)/
'''

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

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

# 运行格式化
poetry run black .
poetry run isort .

# 运行代码检查
poetry run flake8 src/
poetry run mypy src/
poetry run pylint src/

预提交钩子

# 安装pre-commit
poetry add --group dev pre-commit

# 创建.pre-commit-config.yaml
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/psf/black
    rev: 23.11.0
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: ["--profile", "black"]

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.7.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]
EOF

# 安装钩子
poetry run pre-commit install

# 手动运行
poetry run pre-commit run --all-files

迁移脚本

从requirements.txt迁移到Poetry

# 脚本：migrate_to_poetry.sh
#!/bin/bash

echo "迁移到Poetry..."

# 备份当前设置
cp requirements.txt requirements.txt.backup

# 初始化Poetry
poetry init --no-interaction

# 从requirements.txt添加依赖
cat requirements.txt | grep -v "^#" | grep -v "^$" | while read package; do
    # 移除版本说明符用于初始添加
    pkg_name=$(echo $package | cut -d'=' -f1 | cut -d'>' -f1 | cut -d'<' -f1)
    poetry add "$pkg_name"
done

# 安装依赖
poetry install

echo "迁移完成。检查pyproject.toml"
echo "原始requirements.txt已备份到requirements.txt.backup"

格式转换

# Poetry到requirements.txt
poetry export -f requirements.txt --output requirements.txt --without-hashes

# requirements.txt到Poetry
cat requirements.txt | xargs poetry add

# Pipenv到requirements.txt
pipenv requirements > requirements.txt

# Pipenv到Poetry
poetry add $(pipenv requirements | sed 's/==/=/g')

Docker集成

带虚拟环境的Dockerfile

FROM python:3.11-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

# 创建虚拟环境并安装依赖
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用程序
COPY . .

# 以非root用户运行
RUN useradd -m -u 1001 appuser && \
    chown -R appuser:appuser /app
USER appuser

CMD ["python", "app.py"]

带Poetry的Dockerfile

FROM python:3.11-slim as builder

WORKDIR /app

# 安装Poetry
RUN pip install poetry==1.7.0

# 配置Poetry
ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=1 \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

# 复制依赖文件
COPY pyproject.toml poetry.lock ./

# 安装依赖
RUN poetry install --without dev --no-root && rm -rf $POETRY_CACHE_DIR

# 运行时阶段
FROM python:3.11-slim as runtime

WORKDIR /app

# 从构建器复制虚拟环境
ENV VIRTUAL_ENV=/app/.venv \
    PATH="/app/.venv/bin:$PATH"
COPY --from=builder /app/.venv ${VIRTUAL_ENV}

# 复制应用程序
COPY . .

# 以非root用户运行
RUN useradd -m -u 1001 appuser && \
    chown -R appuser:appuser /app
USER appuser

CMD ["python", "app.py"]

最佳实践总结

虚拟环境

始终使用虚拟环境（切勿全局安装）
每个项目一个虚拟环境
将venv/排除在版本控制外（.gitignore）
记录Python版本要求（.python-version）
使用pyenv管理多个Python版本

依赖管理

在生产环境中固定确切版本（不使用~、^）
使用pip-tools或Poetry进行依赖解析
分离开发和生产依赖
使用锁定文件（poetry.lock、带哈希的requirements.txt）
定期更新依赖以提高安全性
记录为何固定特定版本

项目结构

对包使用src/布局
将测试与源代码分离
包含全面的.gitignore
添加带设置说明的README.md
现代项目使用pyproject.toml

安全性

永不提交.env文件
使用python-dotenv处理环境变量
使用pip-audit或safety扫描依赖
在requirements.txt中使用哈希
保持依赖最小化
定期更新安全补丁

开发工作流

使用预提交钩子提高代码质量
配置格式化工具（black、isort）
使用类型提示和mypy
使用pytest编写测试
在README中记录设置步骤

快速参考命令

# venv基础
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip freeze > requirements.txt

# Poetry基础
poetry new project
poetry init
poetry add package
poetry install
poetry shell
poetry run python script.py

# pyenv基础
pyenv install 3.11.5
pyenv local 3.11.5
pyenv virtualenv 3.11.5 myenv

# pip-tools基础
pip-compile requirements.in
pip-sync requirements.txt
pip-compile --upgrade

# 常见任务
pip list --outdated
pip check
poetry show --outdated
poetry update

备注

优先使用Poetry或pip-tools而非手动管理requirements.txt
使用pyenv管理多个Python版本
在安装包前始终激活虚拟环境
保持依赖记录和更新
使用锁定文件实现可复现构建
首先在隔离环境中测试依赖更新
配置适当的.gitignore以排除虚拟环境
使用类型提示和静态分析工具（mypy）
设置CI/CD以验证依赖安装
定期对依赖进行安全审计