managing-python-dependencies

Python Dependency Management Rule

[!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.

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

Default: venv + pip

If no dependency manager is detected, use venv + pip + requirements.txt as the default:

# Initialize environment
python3 -m venv .venv

# Add dependencies
.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.

Prohibited

• NEVER run pip install globally
• NEVER override an existing dependency manager with a different one