pip-weigh

"Know the cost of your imports."

A CLI tool that measures the true disk size of Python packages, including all their dependencies. Perfect for optimizing Docker images, Lambda functions, and understanding your dependency footprint.

Features

• 🔍 Accurate Size Analysis - Measures the real disk footprint of packages and all dependencies
• 📁 Local Project Analysis - Weigh everything your own pyproject.toml pulls in
• 🌐 Cross-Platform Analysis - Check Linux package sizes from macOS/Windows (great for Docker planning)
• 🐍 Python Version Support - Analyze sizes across different Python versions
• 📊 Beautiful Output - Rich terminal output with dependency trees
• 🔄 CI/CD Ready - JSON output and budget checks for pipelines
• ⚡ Fast - Leverages uv's speed and caching

Installation

pip install pip-weigh

Or with uv:

uv pip install pip-weigh

Requirements

• Python 3.9+
• uv must be installed and available in PATH

Usage

Basic Usage

pip-weigh pandas

Output:

📦 pandas (2.1.4)
├── Total Size: 138 MB
├── Self Size: 45 MB
├── Platform: linux
├── Python: 3.12
└── Dependencies (3):
    ├── numpy (1.26.2): 85 MB
    ├── pytz (2023.3): 5 MB
    └── python-dateutil (2.8.2): 3 MB

Analyzing a Local Project

Point pip-weigh at your own project to weigh everything its pyproject.toml pulls in:

pip-weigh .                       # current directory
pip-weigh ./services/api          # any directory with a pyproject.toml
pip-weigh path/to/pyproject.toml  # the file itself
pip-weigh requirements.txt        # a requirements file

If the project has a uv.lock, pip-weigh measures the locked versions, so the number matches what you will actually ship. Pass --no-lock to re-resolve the declared specifiers instead.

Optional extras and PEP 735 dependency groups are excluded by default — dev tooling shouldn't count against your image budget — and can be opted into:

pip-weigh . --extra api --extra worker
pip-weigh . --group test
pip-weigh . --dev

Your project is never modified: no .venv is created in it, no lockfile is written, and the project's own code is not installed. Only its dependency closure is measured.

This makes a neat CI gate:

pip-weigh . --platform linux --budget 250MB

Note: a bare name is always treated as a PyPI package. Write ./rich (not rich) if you mean a local directory of that name.

Cross-Platform Analysis

Check what the size would be on Linux (great for Docker):

pip-weigh torch --platform linux

Accepts linux, macos, windows, or a full target triple such as x86_64-manylinux_2_28 or aarch64-apple-darwin.

Multiple Packages

pip-weigh pandas numpy requests

Each package is measured in isolation, and pip-weigh additionally installs them together to report the deduplicated footprint — shared dependencies are counted once, so the combined total is smaller than the sum of the rows. Skip that extra pass with --no-combined.

Seeing Every Dependency

The tree lists the 15 largest dependencies by default. To see them all:

pip-weigh pandas --limit 0    # no limit
pip-weigh pandas --limit 40   # a specific cap
pip-weigh pandas -v           # verbose implies no limit

--json always includes every dependency regardless of --limit.

JSON Output (for CI/CD)

pip-weigh pandas --json

Budget Check

Fail if a package or project exceeds a size limit:

pip-weigh pandas --budget 100MB
# Exit code 1 if exceeded

Specify Python Version

pip-weigh pandas --python 3.12

CLI Options

Option	Short	Description
--platform	-p	Target platform (linux, macos, windows, or a target triple)
--python		Python version to analyze (e.g., 3.11)
--json	-j	Output as JSON
--budget	-b	Maximum allowed size (e.g., 100MB, 1GB)
--limit	-l	Max dependencies to list (default 15; 0 for all)
--no-deps		Show only the package itself, not dependencies
--extra		Project mode: include an optional-dependency extra (repeatable)
--group		Project mode: include a PEP 735 dependency group (repeatable)
--dev		Project mode: include the dev dependency group
--no-lock		Project mode: re-resolve instead of using uv.lock
--no-combined		Skip the deduplicated total for multiple packages
--verbose	-v	Show detailed output, including every dependency
--check		Check that uv is installed
--version		Show version
--help	-h	Show help message

How It Works

1. Creates a temporary isolated environment using uv
2. Installs the target package(s) with all dependencies, honoring --python-platform so cross-platform estimates use the right wheels
3. Reads the installed .dist-info directories to get the exact resolved set
4. Scans .dist-info/RECORD files for accurate file-to-package mapping
5. Calculates logical sizes (important for Docker/Lambda accuracy)
6. Presents results with a beautiful dependency tree

Why Logical Size Matters

uv uses hardlinks from a global cache, so disk usage tools might show misleading numbers. pip-weigh always reports the logical size - the actual bytes your package would consume in a Docker image or cloud function.

License

MIT