pypa/pip
github.com/pypa/pip ↗ · 1000 files · 7.6 MB
Overview
pip is a Python command-line package installer for developers and automation that resolves dependencies, obtains distributions from indexes, URLs, VCS repositories, and local projects, and installs wheels into Python environments. Its implementation combines vendored dependencies, configurable package discovery, resolvelib dependency resolution, build-backend hooks, and filesystem installation records. This brief describes commit a7002c9771a6c3f0317a4e6b9fbdcd22e643f7b6 using bounded source inspection, including CLI startup, package installation, and configuration persistence.
System map
pip runs as a local CLI process, with additional process boundaries for alternate interpreters, build hooks, and VCS tools. Maintained implementation code lives under _internal, while dependencies are vendored under _vendor. Persistent state is spread across Python installation schemes, configuration files, and caches. Packaging and repository automation are defined separately from runtime command dispatch.
- The root project is named pip, requires Python >=3.10, and exposes pip and pip3 console scripts through pip._internal.cli.main:main; python -m pip delegates to the same function.
- commands_dict maps command names to module paths, classes, and summaries; create_command() imports only the selected module, and Command.main() provides the execution context.
- The architecture distinguishes maintainer-written _internal code from vendored dependencies; direct use of internals is unsupported. Vendoring configuration specifies a namespace, protected files, patches, and an SBOM.
- RequirementCommand constructs preparers and resolvers, while the resolvelib Resolver combines Factory, PipProvider, and a reporter before producing a RequirementSet and installation order.
- Filesystem state has separate owners: wheel installation writes distribution metadata and RECORD, Cache derives artifact directories, and Configuration writes selected INI files outside the checkout.
- External integration boundaries include requests-based PipSession adapters, VCS subprocess execution, and BuildBackendHookCaller instances configured with source directories and build-environment interpreters.
- Flit builds the distribution; build-project.py provisions pinned, hashed build requirements and sets SOURCE_DATE_EPOCH. Nox drives tests, while tag-triggered release automation builds artifacts and publishes through PyPI trusted publishing.
- Maintenance workflows lock inactive closed threads, validate PR checklist bodies, refresh the build lock through a PR, and synchronize documentation redirects using an environment-provided RTD token.
Feature catalog
The command registry exposes installation, artifact preparation, environment inspection, configuration, and diagnostic tools. Installation accepts several requirement sources and destination controls, while lock generation and lock-file consumption are explicitly experimental. Commands share parsing and networking infrastructure but have distinct output and mutation boundaries. The catalog below covers all registered commands, grouping related commands into eight substantive entries.
- install accepts index requirements, VCS URLs, directories, archives, requirements files, constraints, editables, dependency groups, and script metadata; destination controls include --target, --user, --root, and --prefix.
- download resolves and saves distribution artifacts; wheel resolves requirements, saves existing wheels, builds source requirements, and copies successful builds into the requested wheel directory.
- lock generates experimental pylock TOML to a file or stdout, with validity guaranteed only for the current Python version and platform; requirement ingestion also accepts experimental pylock sources.
- uninstall accepts package names or requirements files and supports --yes; its documented exceptions include metadata-less distutils installations and script wrappers created by setup.py develop.
- freeze emits requirements-format inventory, list lists installed packages, show displays package information, and check verifies dependency compatibility; inspect emits versioned JSON containing installed metadata, origins, installer information, and environment markers.
- config dispatches list, edit, get, set, unset, and debug actions; cache dispatches dir, info, list, remove, and purge, returning an error when caching is disabled.
- index versions discovers available versions through PackageFinder and conditionally excludes prereleases; search uses an XML-RPC server's search method and converts XML-RPC faults into CommandError.
- hash computes archive hashes, debug exposes diagnostic information, and help describes commands; completion emits shell integration for bash, zsh, fish, and PowerShell. Global --python can rerun the selected command under another interpreter.
Data flow
Inputs become typed installation requirements through shared command infrastructure. Discovery supplies candidates, and resolution uses metadata and constraints to select concrete distributions. Preparation records artifact paths and provenance before installation writes into an environment scheme. Configuration and caches provide independent persistence paths with their own precedence and identity rules.
- ConfigOptionParser loads Configuration before deriving defaults, applies global, command-specific, then environment sections, and validates string defaults through each option's type checker.
- get_requirements() collects constraints, converts CLI strings and editables into InstallRequirement objects, expands dependency groups, and turns parsed requirements-file entries into user-supplied requirements with config settings.
- RequirementsFileParser recursively resolves nested -r/-c references relative to URLs or local files and rejects recursion; get_file_content() reads HTTP, HTTPS, file URLs, or bare filesystem paths.
- PackageFinder.find_all_candidates() combines evaluated local-file candidates with page candidates and caches the result; a known locked link bypasses those sources and fails immediately if link evaluation rejects it.
- Factory.collect_root_requirements() canonicalizes and intersects matching constraints, tracks user-requested order, and sorts extra-bearing requirements last; Resolver passes these collections into PipProvider and resolvelib.
- Preparation can fetch sidecar metadata and defer full artifacts; full preparation populates local_file_path and DirectUrl provenance, computes a missing source SHA-256, and compares wheel metadata against a previously used sidecar.
- InstallRequirement.install() derives an installation scheme and forwards the wheel, direct origin, and user-requested flag; wheel installation generates launchers and persists INSTALLER, optional direct_url.json and REQUESTED, and rewritten RECORD rows.
- Wheel-cache identity includes the source URL, available hash, subdirectory, and interpreter name/version; HTTP caching uses SafeFileCache adapters, while Configuration tracks parser mutations and saves them to selected INI paths.
Behavior traces
Three concrete flows were followed through their implementation: CLI startup, installation, and configuration persistence. Startup creates a command after parsing global options, and the command establishes shared runtime contexts. Installation branches after resolution for reports and dry runs, then prepares, builds, orders, and installs distributions. Configuration mutation selects a file, loads it, changes a parser, saves it, and affects subsequent option parsing.
- Startup: python -m pip removes a leading empty/current-directory sys.path entry, imports cli.main.main(), installs warning logging, invokes autocomplete(), then calls parse_command().
- Startup continuation: parse_command() validates the command or exits for help/version; main() sets locale and calls create_command(), then Command.main() enters contexts, parses options, configures logging, and dispatches through _run_wrapper().
- Install entry: InstallCommand.run() rejects --user with --target, conditionally checks externally managed environments, chooses user-install behavior, and creates the session, target-aware finder, build tracker, and temporary build directory.
- Install resolution: run() calls get_requirements(), constructs WheelCache, preparer, and resolver, then calls resolve(); Resolver collects roots, creates PipProvider and a reporter, and invokes resolvelib with a 200000-round ceiling.
- Install branch: after resolution, --report writes InstallationReport JSON to a file or stdout; --dry-run prints the planned packages and returns before prepare_linked_requirements_more(), wheel building, and installation.
- Install mutation: preparation completes, non-wheel requirements are built, get_installation_order() orders dependencies first, and install_given_reqs() replaces packages individually; each requirement calls install_wheel(), with failed replacement triggering rollback of its previous uninstall.
- Configuration mutation: config set enters ConfigurationCommand.run(), selects one explicit scope or defaults to an existing site file then user scope, loads Configuration, and calls set_name_value() → set_value() → _save_configuration() → save().
- Configuration persistence continuation: save() ensures the parent directory and writes modified parsers; a later command reloads those files in get_default_values(), applies section precedence, and validates resulting defaults before dispatch.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is claimed. pytest provides unit and functional suites, with Nox provisioning distributions and test dependencies. Inspected tests assert configuration persistence, authentication parsing, dry-run behavior, dependency ordering, and wheel path containment. Platform matrices, skips, network exceptions, and vendored-code exclusions limit what any individual run can establish.
- The inspected configuration uses pytest with strict xfails, unit/integration/network/VCS markers, and socket restrictions; the test dependency group includes pytest-cov, xdist, rerunfailures, subket, and scripttest. These definitions were not executed.
- tests/conftest.py assigns unit/integration markers, prohibits the subprocess-oriented script fixture in unit tests, skips search tests unless enabled, and permits sockets plus CI retries for network-marked tests.
- Configuration tests assert ENV/SITE/USER/GLOBAL precedence; the functional modification pipeline invokes config set/get/unset through PipTestEnvironment and checks that a removed key becomes unavailable.
- Inspected install tests assert dependency-first ordering and verify that --dry-run leaves packages and optional target directories unpopulated, followed by a normal install demonstrating that the same input can install.
- Authentication unit tests parameterize percent-encoded credentials, ordinary credentials, tokens, and credential-free URLs; they assert credential-cache behavior and reset global keyring state after each test.
- Wheel tests exercise escaping console/GUI entry-point names and assert no outside file was written; additional cases cover absolute paths, doubled-slash roots, and a Windows-only different-drive case.
- Inspected CI defines Linux/macOS Python 3.10–3.15 and 3.14t jobs, selected Windows versions sharded into three groups, and a zipapp functional job; PR path filters can skip test jobs. Workflow definitions establish intended checks, not their results.
- Coverage excludes vendored libraries, and typing configuration ignores vendor errors; Nox typecheck examines source, tests, and tooling. The isolation fixture explicitly records incomplete system-configuration isolation, so inspection does not establish exhaustive coverage or hermetic execution.
Risk map
These are source observations and one explicitly labeled failure hypothesis, not confirmed vulnerabilities. Sensitive boundaries include TLS policy, credential retrieval, subprocess execution, and installation outside the checkout. Existing containment checks and hash checks are meaningful protections, but their scope must be preserved. Build-dependency policy and per-package mutation deserve particular attention because they differ from assumptions users may make about the parent install.
- Trusted-host adapters intentionally call certificate verification with verify=False and may cache those responses; ordinary HTTPS uses the secure adapter. Changes to host matching or adapter mounting affect transport trust and cache contents.
- Authentication retrieves URL/index credentials and netrc data, strips credentials from request URLs, and adds Basic Auth; 401 handling can recover redirected URL credentials, consult keyring, prompt, and resend the request.
- config edit executes a shell command built from --editor, VISUAL, or EDITOR and a quoted configuration filename; the implementation rejects filenames containing a double quote but deliberately retains shell semantics for the editor command.
- Wheel installation writes into purelib/platlib and scheme-specific destinations, enforcing archive-path containment and entry-point-name containment before writing files or generating launchers.
- Hash-required preparation rejects VCS URLs, existing directories, and unpinned nondirect requirements, and disables metadata-only fetching; cached built wheels are accepted against recorded source hashes rather than wheel hashes.
- InprocessBuildEnvironmentInstaller hard-codes require_hashes=False and records that build-dependency hash checking is deferred; it also documents imperfect interaction with venv-based build environments.
- Build metadata invokes configured project backend hooks, and VCS operations execute external commands; call_subprocess() copies the process environment, applies explicit additions/removals, and launches arguments through Popen.
- Failure hypothesis: an interrupted config save could truncate its INI file, and a later package failure could leave earlier packages changed. Configuration uses direct write mode, while installation rollback is scoped to the current requirement's previous uninstall. (inferred)
Extension points
Most extension points are internal seams for maintainers rather than public plugin contracts. Commands, action maps, option groups, resolver factories, metadata backends, and VCS registries centralize particular choices. Standards-based build hooks provide an external integration boundary. New behavior should enter through the relevant seam while preserving shared parsing, preparation, and installation invariants.
- New built-in commands attach through commands_dict and a Command subclass; the registry controls help ordering, and create_command() supplies name, summary, and shared constructor arguments through lazy import.
- Sub-actions attach through handler_map() in configuration, cache, and index commands; each run() validates the action and routes remaining arguments to a callable.
- Command options attach through add_options() and cmdoptions helpers/groups; ConfigOptionParser gives them shared configuration loading, section precedence, and default-value validation.
- RequirementCommand.make_resolver() selects resolvelib or legacy implementations; PipProvider.find_matches() delegates candidate construction to Factory with constraints, incompatibilities, and installed-candidate preference.
- PackageFinder discovery uses a LinkCollector callback plus link evaluation; its locked-link branch provides a dedicated path for exact artifact selection without querying ordinary indexes or find-links sources.
- Metadata implementations conform to Backend's Distribution and Environment types; select_backend() caches the choice, with Python-version rules and _PIP_USE_IMPORTLIB_METADATA overrides below Python 3.14.
- Build integration has two seams: BuildEnvironmentInstaller defines dependency installation, while ConfiguredBuildBackendHookCaller forwards wheel, sdist, editable, and dependency hooks using the requirement's config_settings.
- VcsSupport.register() instantiates backend classes by name, exposes their schemes and directory markers, and supports unregistering; VersionControl.get_repository_root() is intended for backend-specific detection overrides.
Contributor handoff
Tests and CI were inspected, not executed, and this handoff makes no passing-result claim. Begin edits by reading the command and shared infrastructure that own the requested behavior. Use existing Nox sessions only when execution is authorized, selecting unit checks before relevant functional checks. Preserve interpreter compatibility, installation records, configuration precedence, and vendoring boundaries; historical architecture prose needs verification against source.
- For dispatch changes, read __main__.py, cli/main.py, main_parser.py, and commands/__init__.py first; public console scripts and module invocation converge on this path, while direct in-process main() use is explicitly discouraged.
- For install changes, inspect InstallCommand.run(), RequirementCommand.make_resolver(), Resolver.resolve(), and install_given_reqs(); reporting, dry runs, preparation completion, building, and environment mutation occur at distinct stages.
- For configuration edits, read the action command, Configuration, and ConfigOptionParser together; explicit scope selection, site/user defaults, PIP_CONFIG_FILE behavior, and command-section precedence are separate mechanisms.
- Keep Python minimum changes synchronized between pyproject.toml and __pip-runner__.py; the runner's compatibility check must remain parseable by Python 2 so unsupported interpreters receive the intended error.
- Treat _vendor updates as vendoring work: its configuration names vendor.txt, patches, protected files, and the SBOM. Formatting hooks exclude the vendor tree, and user-facing changes have configured Towncrier fragment categories.
- When execution is authorized, use existing targeted sessions such as nox -s test-3.10 -- tests/unit/test_wheel.py or tests/functional/test_configuration.py; Nox provisions an sdist and dependencies before pytest. Those sessions and CI were inspected, not executed here.
- Use the stricter Nox typecheck session and repository formatting checks for relevant changes; its typing config excludes fixture data and ignores vendor errors. Unit tests cannot use the functional script fixture, and network-marked tests receive special socket/retry handling.
- Verify architecture prose against current code: anatomy describes argparse and a build_env.py module, while the implementation uses optparse-based ConfigOptionParser and build_env package interfaces. The architecture index itself says documentation is incomplete.
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 655 | 94% |
| Markdown | 46 | docs/config |
| TOML | 35 | 5% |
| YAML | 15 | docs/config |
| HTML | 14 | docs/config |
| JSON | 2 | docs/config |
| Shell | 2 | 0% |
| C | 1 | 0% |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (453 files)
Repository structure
| Top-level path | Files |
|---|---|
src/ | 453 |
tests/ | 364 |
docs/ | 111 |
news/ | 20 |
tools/ | 16 |
.github/ | 15 |
build-project/ | 4 |
.devcontainer/ | 2 |
Docs found: docs/html/cli/index.mddocs/html/development/issue-triage.mddocs/html/getting-started.mddocs/html/index.mddocs/html/installation.mddocs/html/reference/build-system.mddocs/html/reference/index.mddocs/html/reference/inspect-report.mddocs/html/reference/installation-report.mddocs/html/reference/requirement-specifiers.md
Package
pyproject.toml — pip._vendor, 0 declared dependencies.
CI & config entrypoints
.github/workflows/lock-threads.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/check-pr-template.yml— GitHub Actions workflow.github/workflows/update-build-project-lock.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/update-rtd-redirects.yml— GitHub Actions workflow
Structural health signals
Average score 6.1/10 across 96 analyzed source files; 77 hotspots surfaced.
src/pip/_vendor/distro/distro.py— 1395 lines, score 5 (Large file, Deep nesting)src/pip/_vendor/pygments/lexers/python.py— 1130 lines, score 5 (Large file, Deep nesting)src/pip/_vendor/pygments/filters/__init__.py— 942 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
a7002c9771a62026-09-23 — Merge pull request #14303 from edgarrmondragon/bump-platformdirsf800f64e2f552026-08-13 — Upgrade platformdirs to 4.11.12892d13b34a202026-09-21 — Merge pull request #14311 from pypa/update-build-project-lockfa079e3ba3f12026-09-21 — Update build-project/pylock.toml2b28a816d0432026-09-08 — Merge pull request #14302 from pypa/pre-commit-ci-update-config