Back to Details

managing-python-dependencies

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Python Dependency Management Rule

Python依赖管理规则

[!CAUTION] BEFORE any 
pip install
: You MUST first detect the project's existing dependency manager and use it correctly. Do NOT override the project's established tooling.
[!CAUTION] 在执行任何
pip install
之前：你必须先检测项目现有的依赖管理器并正确使用它。不得替换项目已采用的工具链。

Dependency Manager Detection

依赖管理器检测

Before installing ANY Python package, check the workspace for these files in priority order:
  1. Signal: 
    uv.lock
    or 
    pyproject.toml
    with 
    [tool.uv]
    • Tool: uv
    • Install: 
      uv add <package>
    • Setup: 
      uv sync
  2. Signal: 
    pyproject.toml
    with 
    [tool.poetry]
    • Tool: Poetry
    • Install: 
      poetry add <package>
    • Setup: 
      poetry install
  3. Signal: 
    Pipfile
    • Tool: Pipenv
    • Install: 
      pipenv install <package>
    • Setup: 
      pipenv install
  4. Signal: 
    environment.yml
    • Tool: Conda
    • Install: 
      conda install <package>
    • Setup: 
      conda env create -f environment.yml
  5. Signal: 
    requirements.txt
    only
    • Tool: venv + pip
    • Install: 
      .venv/bin/pip install <package>
    • Setup: 
      .venv/bin/pip install -r requirements.txt
  6. Signal: None of the above
    • Tool: venv + pip (default)
    • Install: 
      .venv/bin/pip install <package>
    • Setup: 
      .venv/bin/pip install -r requirements.txt
在安装任何Python包之前，请按优先级顺序检查工作区中的以下文件：
  1. 标识文件： 
    uv.lock
    或包含
    [tool.uv]
    的
    pyproject.toml
    • 工具： uv
    • 安装命令： 
      uv add <package>
    • 环境搭建： 
      uv sync
  2. 标识文件： 包含
    [tool.poetry]
    的
    pyproject.toml
    • 工具： Poetry
    • 安装命令： 
      poetry add <package>
    • 环境搭建： 
      poetry install
  3. 标识文件： 
    Pipfile
    • 工具： Pipenv
    • 安装命令： 
      pipenv install <package>
    • 环境搭建： 
      pipenv install
  4. 标识文件： 
    environment.yml
    • 工具： Conda
    • 安装命令： 
      conda install <package>
    • 环境搭建： 
      conda env create -f environment.yml
  5. 标识文件： 仅存在
    requirements.txt
    • 工具： venv + pip
    • 安装命令： 
      .venv/bin/pip install <package>
    • 环境搭建： 
      .venv/bin/pip install -r requirements.txt
  6. 标识文件： 以上文件均不存在
    • 工具： venv + pip（默认）
    • 安装命令： 
      .venv/bin/pip install <package>
    • 环境搭建： 
      .venv/bin/pip install -r requirements.txt

Default: venv + pip

默认方案：venv + pip

If no dependency manager is detected, use venv + pip + requirements.txt as the default:
bash
undefined
如果未检测到任何依赖管理器，默认使用venv + pip + requirements.txt：
bash
undefined

Initialize environment

初始化环境

python3 -m venv .venv
python3 -m venv .venv

Add dependencies

添加依赖

.venv/bin/pip install <package>
.venv/bin/pip install <package>

Preserve state

保存依赖状态

.venv/bin/pip freeze > requirements.txt

**Rules for venv + pip workflow:**

-   Always use `.venv/bin/pip` or `.venv/bin/python` (explicit path).
-   After installing, run: `.venv/bin/pip freeze > requirements.txt`.
-   When setting up: `.venv/bin/pip install -r requirements.txt`.
.venv/bin/pip freeze > requirements.txt

**venv + pip工作流规则：**

-   始终使用`.venv/bin/pip`或`.venv/bin/python`（显式路径）。
-   安装完成后，执行：`.venv/bin/pip freeze > requirements.txt`。
-   搭建环境时执行：`.venv/bin/pip install -r requirements.txt`。

Prohibited

禁止操作

  • NEVER run 
    pip install
    globally
  • NEVER override an existing dependency manager with a different one
  • 绝对不要全局执行
    pip install
  • 绝对不要用其他工具替换已有的依赖管理器