Pipwatch

Detect import statements in Python files and install the corresponding PyPI packages.

Pipwatch parses your Python files for imports, filters out standard library modules, maps import names to PyPI package names where they differ (e.g. PIL to pillow, cv2 to opencv-python), and installs whatever is missing.

Features

Import Detection

• Parses import statements using the AST module and filters out standard library modules
• Also detects # pip install comments and version specifiers in your code
• Maps import names to correct PyPI package names (e.g. sklearn -> scikit-learn)
• Skips packages that are already installed

Mapping Registry

• Package mappings hosted on GitHub and fetched at runtime
• Local cache with 24-hour TTL so it doesn't hit the network on every run
• Falls back to bundled mappings.json when offline
• New mappings can be added via pull request

CLI Flags

• --dry-run - Preview what would be installed without installing anything
• --generate - Generate a requirements.txt file from detected dependencies
• --verbose - Enable detailed debug logging
• --yes - Auto-confirm installations (useful for CI)
• --output - Specify custom output path for generated requirements files
• --update-mappings - Fetch latest mappings from GitHub
• --clear-cache - Clear cached mappings
• --show-mappings - Show mapping statistics

Directory Scanning

• Point pipwatch at a directory instead of a single file to scan everything
• Automatically skips .venv, node_modules, __pycache__, build, dist, and other junk directories

Installer Support

• Works with both pip and uv — if uv is on your PATH, pipwatch will use it automatically

Installation

pip install pipwatch

or with uv:

uv add pipwatch

For development:

pip install pipwatch[dev]

Usage

Basic Usage

Analyze a single file:

pipwatch script.py

Analyze all Python files in the current directory & subdirectories:

pipwatch .

Analyze all Python files in a specific folder:

pipwatch myfolder/

Dry Run (Preview Only)

See what would be installed without installing:

pipwatch script.py --dry-run

Or for an entire directory:

pipwatch . --dry-run

Example output:

INFO: Analyzing script.py...
INFO: Found the following dependencies from import statements:
INFO:   • bs4 → beautifulsoup4
INFO:   • numpy
INFO:   • pandas

[DRY RUN] Would install the following packages:
  • beautifulsoup4
  • numpy
  • pandas

Generate Requirements File

Create a requirements.txt from your code:

pipwatch script.py --generate

Or with a custom output path:

pipwatch script.py --generate --output my-requirements.txt

Auto-Install (No Prompts)

For automation and CI:

pipwatch script.py --yes

Verbose Mode

Get detailed debug information:

pipwatch script.py --verbose

Manage Mappings

Update mappings from GitHub:

pipwatch --update-mappings

Show mapping statistics:

pipwatch --show-mappings

Clear cached mappings:

pipwatch --clear-cache

Package Name Mappings

Pipwatch includes 50+ mappings for cases where the import name differs from the PyPI package name:

How It Works

1. Parse - Parses your Python file using the AST module
2. Filter - Removes standard library imports
3. Analyze - Scans for # pip install comments and version specifiers
4. Map - Maps import names to PyPI package names
5. Check - Checks which packages are already installed
6. Install/Generate - Installs missing packages or generates requirements.txt

Mapping Resolution

The mapping system loads from three sources, trying each in order:

┌─────────────────┐
│  mappings.json  │ (GitHub)
│   (Remote)      │
└────────┬────────┘
         │ Fetch (once per day)
         ▼
┌─────────────────┐
│  Local Cache    │ (~/.pipwatch/)
│  (24hr TTL)     │
└────────┬────────┘
         │ Fallback
         ▼
┌─────────────────┐
│  Bundled File   │ (Offline support)
│  (Built-in)     │
└─────────────────┘

Contributing Mappings

Found a missing mapping? See docs/CONTRIBUTING_MAPPINGS.md for how to add one.

Development

Setup

git clone https://github.com/Felixdiamond/pipwatch.git
cd pipwatch
pip install -e ".[dev]"

Run Tests

pytest tests/

With coverage:

pytest tests/ --cov=src/pipwatch --cov-report=term-missing

Code Formatting

black src/ tests/
isort src/ tests/
ruff check src/ tests/ --fix

Update Mappings

Use the helper script to add or discover import-to-package mappings in src/pipwatch/mappings.json.

Add a single mapping (validated against PyPI):

python scripts/populate_mappings.py add PIL pillow --category image-processing

Preview without writing:

python scripts/populate_mappings.py add PIL pillow --category image-processing --dry-run

Discover mappings from your installed packages and preview:

python scripts/populate_mappings.py discover

Apply discovered mappings:

python scripts/populate_mappings.py discover --apply

Preview discovered mappings without writing:

python scripts/populate_mappings.py discover --apply --dry-run

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License

Created by Felix Dawodu