Python Virtual Environment Manager Skill

Python虚拟环境管理器技能

Python virtual environment management, dependency handling, and project setup automation.

Python虚拟环境管理、依赖处理与项目搭建自动化。

Instructions

使用说明

You are a Python environment and dependency expert. When invoked:

Virtual Environment Management:
- Create and configure virtual environments
- Manage Python versions with pyenv
- Set up isolated development environments
- Handle multiple Python versions per project
- Configure environment activation scripts
Dependency Management:
- Generate and manage requirements.txt
- Use modern tools (pip-tools, poetry, pipenv)
- Lock dependencies with hashes
- Handle dev vs production dependencies
- Resolve dependency conflicts
Project Setup:
- Initialize new Python projects
- Configure project structure
- Set up testing frameworks
- Configure linting and formatting
- Create reproducible environments
Troubleshooting:
- Fix import errors
- Resolve version conflicts
- Debug installation issues
- Handle platform-specific dependencies
- Clean corrupted environments
Best Practices: Provide guidance on Python packaging, versioning, and environment isolation

你是Python环境与依赖管理专家。被调用时需执行以下操作：

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

Virtual Environment Tools Comparison

虚拟环境工具对比

venv (Built-in)

venv（内置工具）

bash

undefined

bash

undefined

Pros: Built-in, no installation needed

Cons: Basic features, manual workflow

Create environment

python3 -m venv venv

Activate (Linux/Mac)

source venv/bin/activate

Activate (Windows)

venv\Scripts\activate

Deactivate

deactivate

Install dependencies

pip install -r requirements.txt

undefined

pip install -r requirements.txt

undefined

virtualenv (Enhanced)

virtualenv（增强版）

bash

undefined

bash

undefined

Pros: More features, faster than venv

Cons: Requires installation

Install

pip install virtualenv

Create with specific Python version

virtualenv -p python3.11 venv

Create with system site-packages

virtualenv --system-site-packages venv

undefined

virtualenv --system-site-packages venv

undefined

Poetry (Modern, Recommended)

Poetry（现代化工具，推荐使用）

bash

undefined

bash

undefined

Pros: Dependency resolution, packaging, publishing

Cons: Learning curve

Install

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

Create new project

poetry new my-project

Initialize existing project

poetry init

Add dependencies

poetry add requests poetry add --group dev pytest

Install dependencies

poetry install

Run commands in virtual environment

poetry run python script.py poetry run pytest

Activate shell

poetry shell

Update dependencies

poetry update

Show dependency tree

poetry show --tree

undefined

poetry show --tree

undefined

Pipenv

bash

undefined

bash

undefined

Pros: Automatic venv, Pipfile format

Cons: Slower than alternatives

Install

pip install pipenv

Install dependencies

pipenv install requests

Install dev dependencies

pipenv install --dev pytest

Activate environment

pipenv shell

Run command

pipenv run python script.py

Generate requirements.txt

pipenv requirements > requirements.txt

undefined

pipenv requirements > requirements.txt

undefined

pyenv (Python Version Manager)

pyenv（Python版本管理器）

bash

undefined

bash

undefined

Install multiple Python versions

Manage Python versions per project

Install

curl https://pyenv.run | bash

Install Python version

pyenv install 3.11.5 pyenv install 3.12.0

List available versions

pyenv install --list

Set global version

pyenv global 3.11.5

Set local version (per directory)

pyenv local 3.11.5

List installed versions

pyenv versions

Show current version

pyenv version

undefined

pyenv version

undefined

Usage Examples

使用示例

@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

@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

Project Setup Workflows

项目搭建流程

Basic Project with venv

使用venv搭建基础项目

bash

undefined

bash

undefined

Create project directory

mkdir my-project cd my-project

Create virtual environment

python3 -m venv venv

Activate environment

source venv/bin/activate # Linux/Mac

or

venv\Scripts\activate # Windows

Upgrade pip

pip install --upgrade pip

Install dependencies

pip install requests pytest black flake8

Freeze dependencies

pip freeze > requirements.txt

Create .gitignore

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

undefined

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

undefined

Modern Project with Poetry

使用Poetry搭建现代化项目

bash

undefined

bash

undefined

Create new project with structure

poetry new my-project cd my-project

Project structure created:

my-project/

├── pyproject.toml

├── README.md

├── my_project/

│ └── init.py

└── tests/

└── init.py

Add dependencies

poetry add requests httpx pydantic poetry add --group dev pytest pytest-cov black flake8 mypy

Install dependencies

poetry install

Configure 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

undefined

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

undefined

Initialize Existing Project

初始化已有项目

bash

undefined

bash

undefined

Navigate to project

cd existing-project

Initialize poetry

poetry init

Follow interactive prompts, then add dependencies

poetry add $(cat requirements.txt)

Add dev dependencies

poetry add --group dev pytest black flake8

Create virtual environment

poetry install

Verify installation

poetry run python -c "import requests; print(requests.version)"

undefined

poetry run python -c "import requests; print(requests.version)"

undefined

Dependency Management

依赖管理

requirements.txt Best Practices

requirements.txt最佳实践

bash

undefined

bash

undefined

Basic requirements.txt

requests==2.31.0 django==4.2.7 celery==5.3.4

With hashes for security (pip-tools)

pip-compile --generate-hashes requirements.in

Separate files

requirements/ ├── base.txt # Common dependencies ├── development.txt # Dev dependencies ├── production.txt # Production dependencies └── testing.txt # Test dependencies

development.txt

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

Install from specific file

pip install -r requirements/development.txt

undefined

pip install -r requirements/development.txt

undefined

Using pip-tools (Recommended)

使用pip-tools（推荐）

bash

undefined

bash

undefined

Install pip-tools

pip install pip-tools

Create requirements.in

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

Compile to requirements.txt with pinned versions

pip-compile requirements.in

Install from compiled requirements

pip-sync requirements.txt

Update dependencies

pip-compile --upgrade requirements.in

Compile with hashes for security

pip-compile --generate-hashes requirements.in

undefined

pip-compile --generate-hashes requirements.in

undefined

Poetry Dependency Management

Poetry依赖管理

bash

undefined

bash

undefined

Add dependency with version constraint

poetry add "django>=4.2,<5.0"

Add with specific version

poetry add django@4.2.7

Add from git

poetry add git+https://github.com/user/repo.git

Add from local path

poetry add --editable ./local-package

Add with extras

poetry add "celery[redis,auth]"

Update specific package

poetry update django

Update all packages

poetry update

Show outdated packages

poetry show --outdated

Remove package

poetry remove requests

Export to requirements.txt

poetry export -f requirements.txt --output requirements.txt poetry export --without-hashes -f requirements.txt --output requirements.txt

undefined

poetry export -f requirements.txt --output requirements.txt poetry export --without-hashes -f requirements.txt --output requirements.txt

undefined

Development vs Production Dependencies

开发与生产环境依赖区分

bash

undefined

bash

undefined

Poetry approach

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

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

Install without dev dependencies

poetry install --without dev

Install only specific groups

poetry install --only dev

pip-tools approach

requirements.in (production)

django>=4.2 requests

requirements-dev.in (development)

-r requirements.in pytest>=7.4 black>=23.11 flake8>=6.1

Compile both

pip-compile requirements.in pip-compile requirements-dev.in

undefined

pip-compile requirements.in pip-compile requirements-dev.in

undefined

Python Version Management

Python版本管理

Using pyenv

使用pyenv

bash

undefined

bash

undefined

Install pyenv

curl https://pyenv.run | bash

Add to shell configuration (.bashrc, .zshrc)

export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)" eval "$(pyenv virtualenv-init -)"

Install Python versions

pyenv install 3.11.5 pyenv install 3.12.0

Set global version

pyenv global 3.11.5

Set local version (creates .python-version file)

pyenv local 3.11.5

Create virtual environment with specific version

pyenv virtualenv 3.11.5 my-project-env

Activate virtual environment

pyenv activate my-project-env

Deactivate

pyenv deactivate

List virtual environments

pyenv virtualenvs

Delete virtual environment

pyenv uninstall my-project-env

undefined

pyenv uninstall my-project-env

undefined

Using pyenv with Poetry

结合pyenv与Poetry使用

bash

undefined

bash

undefined

Set local Python version

pyenv local 3.11.5

Initialize Poetry project

poetry init

Poetry will use pyenv's Python version

poetry env use python

Or specify version explicitly

poetry env use 3.11

List Poetry environments

poetry env list

Remove environment

poetry env remove python3.11

Show environment info

poetry env info

undefined

poetry env info

undefined

Project Structure Best Practices

项目结构最佳实践

Small Project

小型项目

my-project/
├── .gitignore
├── README.md
├── requirements.txt
├── setup.py  (optional)
├── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py

my-project/
├── .gitignore
├── README.md
├── requirements.txt
├── setup.py  (optional)
├── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py

Medium Project

中型项目

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

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

Large Project with Poetry

使用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

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

Common Issues & Solutions

常见问题与解决方案

Issue: ModuleNotFoundError

问题：ModuleNotFoundError

bash

undefined

bash

undefined

Check if virtual environment is activated

which python # Should point to venv/bin/python

Verify package is installed

pip list | grep package-name

Reinstall package

pip install --force-reinstall package-name

Check Python path

python -c "import sys; print('\n'.join(sys.path))"

Fix: Activate virtual environment

source venv/bin/activate

Fix: Install in editable mode for local development

pip install -e .

undefined

pip install -e .

undefined

Issue: Dependency Conflicts

问题：依赖冲突

bash

undefined

bash

undefined

Check for conflicts

pip check

Show dependency tree

pip install pipdeptree pipdeptree

Using Poetry (better conflict resolution)

poetry add package-name

Poetry will resolve conflicts automatically

Force specific version

pip install "package==1.2.3"

Use pip-tools to resolve

pip-compile --resolver=backtracking requirements.in

undefined

pip-compile --resolver=backtracking requirements.in

undefined

Issue: Multiple Python Versions Confusion

问题：多Python版本混淆

bash

undefined

bash

undefined

Check current Python version

python --version which python

Use specific version explicitly

python3.11 -m venv venv

With pyenv

pyenv versions # List installed versions pyenv which python # Show current python path

Set specific version for project

pyenv local 3.11.5

undefined

pyenv local 3.11.5

undefined

Issue: Corrupted Virtual Environment

问题：损坏的虚拟环境

bash

undefined

bash

undefined

Delete and recreate

rm -rf venv/ python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

With Poetry

poetry env remove python3.11 poetry install

undefined

poetry env remove python3.11 poetry install

undefined

Issue: SSL Certificate Errors

问题：SSL证书错误

bash

undefined

bash

undefined

Temporary workaround (NOT for production)

pip install --trusted-host pypi.org --trusted-host pypi.python.org package-name

Better solution: Update certificates

pip install --upgrade certifi

macOS specific

/Applications/Python\ 3.11/Install\ Certificates.command

undefined

/Applications/Python\ 3.11/Install\ Certificates.command

undefined

Issue: Permission Denied

问题：权限拒绝

bash

undefined

bash

undefined

Don't use sudo with pip in virtual environment!

Recreate venv with proper permissions

Fix ownership

chown -R $USER:$USER venv/

Use user install only if not in venv

pip install --user package-name

undefined

pip install --user package-name

undefined

Environment Variables and Configuration

环境变量与配置

.env Files

.env文件

bash

undefined

bash

undefined

Install python-decouple or python-dotenv

poetry add python-dotenv

Create .env file

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

Load in 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')

undefined

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')

undefined

Environment-Specific Settings

环境专属配置

python

undefined

python

undefined

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'

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'

Select config based on environment

config = { 'development': DevelopmentConfig, 'production': ProductionConfig, 'testing': TestingConfig, 'default': DevelopmentConfig }

def get_config(): env = os.getenv('FLASK_ENV', 'default') return configenv

undefined

config = { 'development': DevelopmentConfig, 'production': ProductionConfig, 'testing': TestingConfig, 'default': DevelopmentConfig }

def get_config(): env = os.getenv('FLASK_ENV', 'default') return configenv

undefined

Testing Setup

测试环境搭建

pytest Configuration

pytest配置

bash

undefined

bash

undefined

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

Run tests

poetry run pytest

With coverage

poetry run pytest --cov=src --cov-report=html

Run specific test

poetry run pytest tests/test_core.py::test_function_name

undefined

poetry run pytest tests/test_core.py::test_function_name

undefined

Code Quality Tools

代码质量工具

Formatting and Linting

格式化与代码检查

bash

undefined

bash

undefined

Install tools

poetry add --group dev black isort flake8 mypy pylint

pyproject.toml configuration

[tool.black] line-length = 88 target-version = ['py311'] include = '.pyi?$' extend-exclude = ''' /(

directories

.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

[tool.black] line-length = 88 target-version = ['py311'] include = '.pyi?$' extend-exclude = ''' /(

directories

.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

Run formatting

poetry run black . poetry run isort .

Run linting

poetry run flake8 src/ poetry run mypy src/ poetry run pylint src/

undefined

poetry run flake8 src/ poetry run mypy src/ poetry run pylint src/

undefined

Pre-commit Hooks

预提交钩子

bash

undefined

bash

undefined

Install pre-commit

poetry add --group dev pre-commit

Create .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

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

Install hooks

poetry run pre-commit install

Run manually

poetry run pre-commit run --all-files

undefined

poetry run pre-commit run --all-files

undefined

Migration Scripts

迁移脚本

Migrate from requirements.txt to Poetry

从requirements.txt迁移到Poetry

bash

undefined

bash

undefined

Script: migrate_to_poetry.sh

#!/bin/bash

echo "Migrating to Poetry..."

#!/bin/bash

echo "Migrating to Poetry..."

Backup current setup

cp requirements.txt requirements.txt.backup

Initialize Poetry

poetry init --no-interaction

Add dependencies from requirements.txt

Install dependencies

poetry install

echo "Migration complete. Check pyproject.toml" echo "Original requirements.txt backed up to requirements.txt.backup"

undefined

poetry install

echo "Migration complete. Check pyproject.toml" echo "Original requirements.txt backed up to requirements.txt.backup"

undefined

Convert between formats

格式转换

bash

undefined

bash

undefined

Poetry to requirements.txt

poetry export -f requirements.txt --output requirements.txt --without-hashes

requirements.txt to Poetry

cat requirements.txt | xargs poetry add

Pipenv to requirements.txt

pipenv requirements > requirements.txt

Pipenv to Poetry

poetry add $(pipenv requirements | sed 's/==/=/g')

undefined

poetry add $(pipenv requirements | sed 's/==/=/g')

undefined

Docker Integration

Docker集成

Dockerfile with Virtual Environment

带虚拟环境的Dockerfile

dockerfile

FROM python:3.11-slim

WORKDIR /app

dockerfile

FROM python:3.11-slim

WORKDIR /app

Install system dependencies

RUN apt-get update && apt-get install -y
gcc
&& rm -rf /var/lib/apt/lists/*

Copy dependency files

COPY requirements.txt .

Create virtual environment and install dependencies

RUN python -m venv /opt/venv ENV PATH="/opt/venv/bin:$PATH" RUN pip install --no-cache-dir -r requirements.txt

Copy application

COPY . .

Run as non-root

RUN useradd -m -u 1001 appuser &&
chown -R appuser:appuser /app USER appuser

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

undefined

RUN useradd -m -u 1001 appuser &&
chown -R appuser:appuser /app USER appuser

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

undefined

Dockerfile with Poetry

带Poetry的Dockerfile

dockerfile

FROM python:3.11-slim as builder

WORKDIR /app

dockerfile

FROM python:3.11-slim as builder

WORKDIR /app

Install Poetry

RUN pip install poetry==1.7.0

Configure Poetry

ENV POETRY_NO_INTERACTION=1
POETRY_VIRTUALENVS_IN_PROJECT=1
POETRY_VIRTUALENVS_CREATE=1
POETRY_CACHE_DIR=/tmp/poetry_cache

Copy dependency files

COPY pyproject.toml poetry.lock ./

Install dependencies

RUN poetry install --without dev --no-root && rm -rf $POETRY_CACHE_DIR

Runtime stage

FROM python:3.11-slim as runtime

WORKDIR /app

FROM python:3.11-slim as runtime

WORKDIR /app

Copy virtual environment from builder

ENV VIRTUAL_ENV=/app/.venv
PATH="/app/.venv/bin:$PATH" COPY --from=builder /app/.venv ${VIRTUAL_ENV}

Copy application

COPY . .

Run as non-root

RUN useradd -m -u 1001 appuser &&
chown -R appuser:appuser /app USER appuser

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

undefined

RUN useradd -m -u 1001 appuser &&
chown -R appuser:appuser /app USER appuser

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

undefined

Best Practices Summary

最佳实践总结

Virtual Environment

虚拟环境

Always use virtual environments (never install globally)
One virtual environment per project
Keep venv/ out of version control (.gitignore)
Document Python version requirements (.python-version)
Use pyenv for managing multiple Python versions

始终使用虚拟环境（绝不全局安装依赖）
单个项目对应一个虚拟环境
将venv/排除在版本控制外（添加到.gitignore）
记录Python版本要求（.python-version文件）
使用pyenv管理多Python版本

Dependency Management

依赖管理

Pin exact versions in production (no ~, ^)
Use pip-tools or Poetry for dependency resolution
Separate dev and production dependencies
Use lock files (poetry.lock, requirements.txt with hashes)
Regularly update dependencies for security
Document why specific versions are pinned

生产环境固定精确版本（不使用~、^符号）
使用pip-tools或Poetry解决依赖冲突
区分开发与生产环境依赖
使用锁定文件（poetry.lock、带哈希值的requirements.txt）
定期更新依赖以修复安全漏洞
记录固定特定版本的原因

Project Structure

项目结构

Use src/ layout for packages
Keep tests separate from source
Include comprehensive .gitignore
Add README.md with setup instructions
Use pyproject.toml for modern projects

采用src/布局管理包
测试代码与源码分离
配置全面的.gitignore
添加包含搭建说明的README.md
现代化项目使用pyproject.toml

Security

安全

Never commit .env files
Use python-dotenv for environment variables
Scan dependencies with pip-audit or safety
Use hashes in requirements.txt
Keep dependencies minimal
Update regularly for security patches

绝不提交.env文件
使用python-dotenv管理环境变量
使用pip-audit或safety扫描依赖安全问题
requirements.txt中使用哈希值
最小化依赖数量
定期更新依赖获取安全补丁

Development Workflow

开发流程

Use pre-commit hooks for code quality
Configure formatters (black, isort)
Use type hints and mypy
Write tests with pytest
Document setup steps in README

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

Quick Reference Commands

快速参考命令

bash

undefined

bash

undefined

venv basics

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

Poetry basics

poetry new project poetry init poetry add package poetry install poetry shell poetry run python script.py

pyenv basics

pyenv install 3.11.5 pyenv local 3.11.5 pyenv virtualenv 3.11.5 myenv

pip-tools basics

pip-compile requirements.in pip-sync requirements.txt pip-compile --upgrade

Common tasks

pip list --outdated pip check poetry show --outdated poetry update

undefined

pip list --outdated pip check poetry show --outdated poetry update

undefined

Notes

注意事项

Prefer Poetry or pip-tools over manual requirements.txt management
Use pyenv to manage multiple Python versions
Always activate virtual environment before installing packages
Keep dependencies documented and up-to-date
Use lock files for reproducible builds
Test dependency updates in isolated environment first
Configure proper .gitignore to exclude virtual environments
Use type hints and static analysis tools (mypy)
Set up CI/CD to verify dependency installation
Regular security audits of dependencies

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

python-venv-manager

Original

Translation

Python Virtual Environment Manager Skill

Python虚拟环境管理器技能

Instructions

使用说明

Virtual Environment Tools Comparison

虚拟环境工具对比

venv (Built-in)

venv（内置工具）

Pros: Built-in, no installation needed

Pros: Built-in, no installation needed

Cons: Basic features, manual workflow

Cons: Basic features, manual workflow

Create environment

Create environment

Activate (Linux/Mac)

Activate (Linux/Mac)

Activate (Windows)

Activate (Windows)

Deactivate

Deactivate

Install dependencies

Install dependencies

virtualenv (Enhanced)

virtualenv（增强版）

Pros: More features, faster than venv

Pros: More features, faster than venv

Cons: Requires installation

Cons: Requires installation

Install

Install

Create with specific Python version

Create with specific Python version

Create with system site-packages

Create with system site-packages

Poetry (Modern, Recommended)

Poetry（现代化工具，推荐使用）

Pros: Dependency resolution, packaging, publishing

Pros: Dependency resolution, packaging, publishing

Cons: Learning curve

Cons: Learning curve

Install

Install

Create new project

Create new project

Initialize existing project

Initialize existing project

Add dependencies

Add dependencies

Install dependencies

Install dependencies

Run commands in virtual environment

Run commands in virtual environment

Activate shell

Activate shell

Update dependencies

Update dependencies

Show dependency tree

Show dependency tree

Pipenv

Pipenv

Pros: Automatic venv, Pipfile format

Pros: Automatic venv, Pipfile format

Cons: Slower than alternatives

Cons: Slower than alternatives

Install

Install

Install dependencies

Install dependencies

Install dev dependencies

Install dev dependencies

Activate environment

Activate environment

Run command

Run command

Generate requirements.txt

Generate requirements.txt

pyenv (Python Version Manager)