python-venv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Virtual Environment Requirement

Python虚拟环境要求

Core Rule

核心规则

Check for existing virtual environments and reuse them. If none exists, ask user to choose: create new venv, use custom path, or use system Python directly.

检查现有虚拟环境并复用。如果不存在，请询问用户选择：创建新venv、使用自定义路径，或者直接使用系统Python。

When Virtual Environment is REQUIRED

需要使用虚拟环境的场景

Scenario	Required?	Reason
`pip install` / `uv pip install`	✅ YES	Installing packages
Running `.py` files with third-party imports	✅ YES	Needs dependencies
`python script.py` with `requirements.txt`	✅ YES	Project dependencies
Multi-file Python projects	✅ YES	Isolation needed

场景	是否需要	原因
`pip install` / `uv pip install`	✅ 是	安装包操作
运行包含第三方导入的 `.py` 文件	✅ 是	需要依赖
搭配 `requirements.txt` 运行 `python script.py`	✅ 是	项目依赖
多文件Python项目	✅ 是	需要环境隔离

When Virtual Environment is NOT Required

不需要使用虚拟环境的场景

Scenario	Example
Simple stdlib one-liner	`python3 -c "print('hello')"`
Built-in modules only	`python3 -c "import json; ..."`
Version check	`python3 --version`

Standard library modules: os, sys, json, re, math, datetime, pathlib, subprocess, collections, itertools, functools, argparse, logging, urllib, http, socket, threading, multiprocessing, etc.

场景	示例
仅使用标准库的简单单行代码	`python3 -c "print('hello')"`
仅使用内置模块	`python3 -c "import json; ..."`
版本检查	`python3 --version`

标准库模块: os, sys, json, re, math, datetime, pathlib, subprocess, collections, itertools, functools, argparse, logging, urllib, http, socket, threading, multiprocessing, 等。

Workflow (When venv IS Required)

工作流程（需要venv时）

1. Check for existing virtual environment (.venv, venv, env, .env) → If YES, activate and reuse it
2. If NOT exists → Ask user to choose:
   - **Create new venv** (recommended): Create .venv in current directory with uv or python3 -m venv
   - **Use system Python**: Skip venv, use system Python directly
   - **Custom path**: Specify custom path for virtual environment
3. Based on user choice: Create/skip/create-at-path virtual-environment
4. Activate (if venv was created), then proceed with Python commands

1. 检查现有虚拟环境（.venv, venv, env, .env）→ 存在则激活并复用
2. 不存在 → 询问用户选择：
   - **创建新venv**（推荐）：使用uv或python3 -m venv在当前目录创建.venv
   - **使用系统Python**：跳过venv，直接使用系统Python
   - **自定义路径**：指定虚拟环境的自定义路径
3. 根据用户选择：创建/跳过/在指定路径创建虚拟环境
4. 激活（如果创建了venv），然后执行后续Python命令

Detecting Existing Virtual Environment

检测现有虚拟环境

Check in this order (first match wins):

.venv/

→

venv/

→

env/

→

.env/

Also check conda:

conda info --envs

or check if

CONDA_PREFIX

is set.

Priority: Always reuse existing virtual environment to preserve installed packages.

按以下顺序检查（匹配到第一个即终止）：

.venv/

→

venv/

→

env/

→

.env/

同时检查conda环境：

conda info --envs

或检查是否设置了

CONDA_PREFIX

环境变量。

优先级：始终复用现有虚拟环境以保留已安装的包。

Workflow Checklist

工作流检查清单

Before Python operations requiring venv:

Check for existing virtual environment:
```
.venv/
```
,
```
venv/
```
,
```
env/
```
,
```
.env/
```
Check for conda:
```
conda info --envs
```
or
```
CONDA_PREFIX
```
If exists → Reuse it (activate)
If not exists → Ask user: Create new (.venv)? Use system Python? Custom path?
Based on choice: Create / Skip / Create at path
Activate (if venv created), proceed

在执行需要venv的Python操作前：

检查现有虚拟环境：
```
.venv/
```
,
```
venv/
```
,
```
env/
```
,
```
.env/
```
检查conda环境：
```
conda info --envs
```
或
```
CONDA_PREFIX
```
如存在 → 复用（激活）
如不存在 → 询问用户：新建（.venv）？使用系统Python？自定义路径？
根据选择：创建 / 跳过 / 在指定路径创建
激活（如果创建了venv），继续后续操作

Project Type Detection

项目类型检测

File Present	Install Command
`requirements.txt`	`pip install -r requirements.txt`
`pyproject.toml`	`pip install -e .` or `uv pip install -e .`
`pyproject.toml` + `poetry.lock`	`poetry install`
`pyproject.toml` + `uv.lock`	`uv sync`
`setup.py`	`pip install -e .`
`Pipfile`	`pipenv install`
`environment.yml`	`conda env create -f environment.yml`

存在的文件	安装命令
`requirements.txt`	`pip install -r requirements.txt`
`pyproject.toml`	`pip install -e .` 或 `uv pip install -e .`
`pyproject.toml` + `poetry.lock`	`poetry install`
`pyproject.toml` + `uv.lock`	`uv sync`
`setup.py`	`pip install -e .`
`Pipfile`	`pipenv install`
`environment.yml`	`conda env create -f environment.yml`

Quick Reference

快速参考

Task	Linux/macOS	Windows
Create venv (uv)	`uv venv`	`uv venv`
Create venv (standard)	`python3 -m venv .venv`	`python -m venv .venv`
Activate	`source .venv/bin/activate`	`.venv\Scripts\activate`
Install package (uv)	`uv pip install <pkg>`	`uv pip install <pkg>`
Install package (pip)	`pip install <pkg>`	`pip install <pkg>`
Deactivate	`deactivate`	`deactivate`
Conda activate	`conda activate <env>`	`conda activate <env>`

For custom paths: Replace

.venv

with your path in create/activate commands.

For system Python: Skip venv, use

python3

python

directly.

任务	Linux/macOS	Windows
创建venv（uv）	`uv venv`	`uv venv`
创建venv（标准方式）	`python3 -m venv .venv`	`python -m venv .venv`
激活	`source .venv/bin/activate`	`.venv\Scripts\activate`
安装包（uv）	`uv pip install <pkg>`	`uv pip install <pkg>`
安装包（pip）	`pip install <pkg>`	`pip install <pkg>`
退出虚拟环境	`deactivate`	`deactivate`
激活conda环境	`conda activate <env>`	`conda activate <env>`

自定义路径说明：在创建/激活命令中，将

.venv

替换为你的自定义路径即可。

系统Python说明：跳过venv，直接使用

python3

python

命令。

Detailed Patterns

常见模式

For common patterns, scripts, and platform-specific commands, see patterns.md.

如需了解常见模式、脚本和平台特定命令，请查看 patterns.md。

Troubleshooting

问题排查

For troubleshooting guidance, see troubleshooting.md.

如需排查问题的指引，请查看 troubleshooting.md。