Measuring packages¶
Measure a package set¶
All requested packages and their resolved dependencies are installed together in one temporary environment. A shared dependency is installed once and counted once in the global total.
Choose output or save JSON with --json¶
The default terminal report is a compact rich summary. Save the versioned result when another tool, review, or later comparison needs stable data:
On success, standard output is exactly one JSON document. Check schema_version and context.input_kind before using a saved result. --comparison-json produces a versioned comparison document when a compatible baseline is supplied.
Pre-release dependencies¶
Package requests explicitly use --prerelease if-necessary by default. Stable
releases remain preferred, but packages such as apache-airflow==3.0.0 can still
resolve when part of their dependency graph requires a pre-release package:
Use --prerelease disallow for a strict stable-only measurement, or
--prerelease allow when every pre-release candidate may be considered. The
effective policy is recorded in context.resolution_strategy, making results
with different resolver conditions incompatible for baseline comparison.
This setting is separate from --allow-build. Pre-release policy selects
versions; build policy decides whether an sdist build backend may execute.
--prerelease is only available for package requests because locked-project
analysis obtains its resolver policy from the explicit lock.
Explain a total with --explain¶
Add text-only views when you need context for a result:
uvx uv-packsize requests --explain
uvx uv-packsize requests --breakdown
uvx uv-packsize 'package-a' 'package-b' --contributions
--explainshows observed dependency paths and direct, transitive, and shared attribution from installed Core Metadata; it is not resolver provenance.--breakdowngroups deduplicated global bytes by file category and, when available, dependency role.--contributionsshows exclusive, shared, and closure bytes per requested root. Closures are not hypothetical uninstall calculations and must not be summed.
These options change text presentation only, not the JSON result.
Show scripts separately with --bin¶
With --report standard, --bin moves RECORD-owned scripts from the package
table into a separate Binaries table. With --report rich, it leaves the
primary summary and Largest Distributions owned sizes unchanged, then appends
the binary details section. Both layouts preserve the canonical global total,
and --bin never changes JSON bytes.
Inspect an existing environment with --prefix¶
--prefix is read-only: it does not run Python, invoke uv, or change the prefix. Supply every site-packages directory relative to the prefix and its filesystem case rule:
uvx uv-packsize --prefix .venv \
--site-packages lib/python3.12/site-packages \
--case-rule sensitive --json > prefix-analysis.json
--site-packages can be repeated. Each value must be a non-empty, canonical
relative path in the host's native path flavor. Absolute paths, ./..
components, repeated separators, and symlink components are rejected. A
relative --prefix is resolved from the current working directory to its
canonical physical directory before scanning; the prefix itself must not be a
symlink. Windows-style paths are accepted only when the host path flavor is
Windows, and POSIX-style paths only on a POSIX host.
--case-rule sensitive and --case-rule insensitive are trusted declarations,
not filesystem probes. Select the rule that describes the filesystem being
measured; the command does not infer it by probing an existing path. Prefix
analysis is read-only and does not create an environment, install packages,
run Python, invoke uv, or write metadata. The validation and scan are still
best-effort with respect to concurrent changes, so measure a stable prefix and
avoid changing it during the scan (TOCTOU).
Prefix scans use a separate schema and do not support comparisons or budgets.
Existing-prefix JSON is schema v2; its context leaves unknown resolution
fields empty or null and never records the raw prefix or site-packages paths.
With --bin, prefix text output uses the heading Binaries in prefix;
generated script sizes can differ from a fresh temporary installation because
POSIX shebangs can include the installation path. In prefix JSON mode, --bin
is accepted but ignored, preserving the same schema v2 bytes.
Choose a text layout with --report¶
--report rich is the default compact overview. The legacy full plain-text table remains available when a script needs it:
--- Rich Analysis Summary ---
Input kind: fresh-install
Build policy: wheel-only
Completeness: complete
Warnings: none
Distributions: 1
Canonical global size: 1.50 KiB
Distribution-owned aggregate: 1.50 KiB
--- Largest Distributions (Showing 1 of 1) ---
Distribution Owned size
------------ ----------
sample 1.50 KiB
The example is generated from a fixed test result; actual names and sizes depend on the resolved environment. Rich reports show at most five distributions. Their primary summary omits raw requirements, installed paths, resolved versions, context fingerprints, and lock identities. --bin can show script paths and --explain can show installed metadata, so use them carefully when sharing output. Full output and JSON channel details are in the Measurement contract.
Suppress progress with --quiet¶
Use --quiet when a script needs only the final report or JSON document:
It removes routine progress and completion messages, not final output or sanitized errors. JSON bytes are unchanged.
Control ANSI color with --color¶
Color defaults to auto. Force or disable it explicitly when needed:
uvx uv-packsize requests --report rich --color always
uvx uv-packsize requests --report standard --color never
auto decorates only a suitable stdout terminal; --json and --comparison-json ignore color values. The standard/never combination is the legacy text escape for scripts that cannot consume JSON.
Next step¶
- Compare a baseline or enforce a budget for package-request results.
- Measure a locked project when
pyproject.tomlanduv.lockdefine the dependency set.