pypa/virtualenv
github.com/pypa/virtualenv ↗ · 278 files · 2.1 MB
virtualenv A tool for creating isolated virtual python environments.
Overview
virtualenv creates isolated Python environments for developers and tools that need a reusable environment-building API. At commit 571bc2041dae5ecbd250d82ec7ef482cfd3c3b69, it combines interpreter discovery, platform-specific creation, cached installation of seed packages, and shell activation through four plugin groups. Its distinctive boundaries are the target environment, a persistent per-user cache, external python-discovery, and optional pip/PyPI subprocess and network operations.
System map
The runtime is a Python CLI and library organized around a creation session. Discovery, creation, seeding, and activation are selected through installed package metadata. Persistent state lives in app-data folders, while generated environment files live under the chosen destination with a guarded adjacent redirect. Packaging supports wheels, source distributions, and a standalone zipapp.
- The console script targets virtualenv.__main__:run_with_catch; python -m virtualenv reaches the same wrapper, while the package exports cli_run and session_via_cli.
- build_parser discovers the interpreter before constructing CreatorSelector, SeederSelector, and ActivationSelector; Session.run executes create → seed → activate → final configuration write.
- Builtin discovery delegates get_interpreter to python-discovery; local PythonInfo is a compatibility re-export, and python-discovery>=1.6 is a runtime dependency.
- Creator entry points include CPython, PyPy, GraalPy, RustPython, and stdlib venv implementations; CreatorSelector filters them through can_create and aliases the first compatible VirtualenvBuiltin as builtin.
- AppDataDiskFolder separates interpreter JSON, downloaded wheel house, versioned installation images, update logs, and extracted zipapp resources; make_app_data chooses disk, read-only, or temporary storage.
- Seeding integrates distlib script generation, pip download subprocesses, and PyPI JSON metadata; FromAppData installs images directly, whereas PipInvoke runs pip under the created interpreter.
- Hatchling and hatch-vcs build the package and generate version.py; the custom SbomBuildHook conditionally embeds a CycloneDX SBOM, and tox defines interpreter tests, documentation, typing, package checks, and zipapp builds.
- make_zipapp bundles hashed, locked pure-Python wheels and a custom import loader; release CI publishes distributions to PyPI and zipapp/SBOM assets to GitHub, then updates get-virtualenv.
Feature catalog
The primary command builds an environment at a positional destination, with selectable interpreter and creation strategy. Users control seed packages, activation scripts, configuration sources, and cache maintenance. The library API returns a session for inspecting environment properties. Additional outputs include environment metadata, cache/VCS markers, and a provisional project discovery redirect.
- --python/-p accepts repeated paths, identifiers, or version specifiers and uses the first successful discovery; --try-first-with supplies preferred candidates, and the default specification is sys.executable.
- Creation options include --creator, --copies/--always-copy, --symlinks, --system-site-packages, --clear, and --no-vcs-ignore; unsupported copy/link capabilities constrain available flags.
- --seeder defaults to app-data with pip as an alternative; --no-seed/--without-pip disables seeding, and seed options select embed, bundle, none, or exact versions plus local search directories and downloads.
- setuptools defaults to none for targets >=3.12; --wheel and --no-wheel are deprecated no-ops, and enabled bundled seeders reject targets below the oldest bundled release, currently 3.9.
- --activators selects a comma-separated subset, defaulting to all supported implementations; eight registered activators cover bash, batch, cshell, fish, nushell, powershell, Python, and xonsh, with --prompt customization.
- Users can override options through VIRTUALENV_* variables or a [virtualenv] INI section, select VIRTUALENV_CONFIG_FILE, and configure --app-data, --read-only-app-data, --reset-app-data, or --upgrade-embed-wheels.
- cli_run creates and returns a Session; session_via_cli constructs the session without running creation, exposing creator, interpreter, seeder, and activators for callers.
- Creation writes CACHEDIR.TAG and normally .gitignore; provisional --venv-redirect/--no-venv-redirect controls an adjacent .venv file, while CLI reporting offers verbosity, version, traceback, and a completion/package summary.
Data flow
CLI arguments, environment variables, and INI values become a provenance-aware options namespace. Discovery yields PythonInfo, and the creator owns destination layout and environment metadata shared by seeders and activators. Wheels move through verification, cache selection, installation images, and generated console scripts. Update processes persist version history for later runs.
- VirtualEnvConfigParser resolves environment defaults before INI defaults, then argparse applies CLI values; VirtualEnvOptions records source provenance used to arbitrate copy versus symlink settings.
- get_discover parses plugin selection and discovery-specific arguments; Discover.interpreter caches run() once, and Builtin passes specifications, preferred executables, app-data, and the supplied environment to external discovery.
- Describe maps target Python install paths to destination script_dir, purelib, and platlib; the same Creator object supplies these paths to seeding and activation.
- Creator.set_pyenv_cfg records interpreter home, implementation, versions, executable, command, and virtualenv version; PyEnvCfg.write normalizes only designated path keys and collapses line boundaries before UTF-8 output.
- get_wheel conditionally consults from_bundle before downloading; from_bundle combines embedded wheels, update history, and extra search directories, choosing a newer local candidate when compatible.
- FromAppData retrieves wheels in threads, keys images by target release, installer class, and wheel stem, builds missing images under a file lock, and copies or links image contents into purelib before generating console scripts.
- Activation converts destination, environment name, prompt, bin name, and Tcl/Tk values into quoted substitutions; templates are replaced in one pass and written to bin_dir, using UTF-8 BOM for PowerShell.
- Periodic updates persist started/completed timestamps and wheel histories in per-distribution JSON; subsequent bundle requests select eligible cached versions using one-hour CI and 28-day minor-release grace conditions.
Behavior traces
Source walks followed startup and selection, environment creation and cached seeding, activation, and persistent wheel updates. Startup performs repeated partial parsing because selected implementations contribute additional arguments. Creation has separate builtin and stdlib venv branches. Activation generates scripts that users subsequently source; updates can continue in a background process.
- Startup: run_with_catch → run → cli_run → session_via_cli → build_parser; build_parser configures reporting, loads app-data, handles maintenance commands, then obtains discover.interpreter before selecting creation components.
- Interpreter selection: get_discover → plugin.add_parser_arguments → plugin(options) → Discover.interpreter → Builtin.run → get_interpreter; failed specifications fall through until one succeeds, otherwise build_parser raises RuntimeError.
- Builtin creation: Session._create → Creator.run → ViaGlobalRefVirtualenvBuiltin.create → ensure_directories → initial pyvenv.cfg write → applicable source.run calls → superclass patch installation; Creator.run then writes markers, rebuilds metadata, and considers the redirect.
- Stdlib creation branch: Venv.create calls create_inline when the target is the current system interpreter, otherwise create_via_sub_process → get_host_create_cmd → run_cmd; both avoid pip and then ensure library directories and apply shared-library support.
- Cached seeding: Session._seed → FromAppData.run → _get_seed_wheels → get_wheel; acquisition threads try local resolution before a download fallback unless download was explicitly selected, then aggregate failures before installation.
- Installation: installer_class chooses symlink only with --symlink-app-data and pip>=19.3; _build_wheel_image → has_image/build_image → validated extraction → generated metadata/RECORD → install → prior-version uninstall → image sync → console entry-point creation.
- Bash activation: Session._activate → BashActivator.generate → replacements → instantiate_template → _generate writes bin/activate; sourcing it runs deactivate nondestructive, selects VIRTUAL_ENV, and prepends its bin directory to PATH, while deactivate restores saved state.
- Persistent update: from_bundle → periodic_update → handle_auto_update records a start and trigger_update launches do_update; _run_do_update downloads eligible wheels and writes completion/history, while --upgrade-embed-wheels invokes manual_upgrade before interpreter selection.
Testing signals
Tests and CI were inspected, not executed; their existence establishes intended checks, not passing results. The inspected suite uses pytest, coverage, mocks, parallel workers, Hypothesis properties, and separate tooling checks. Coverage includes CLI selection, discovery, cached seeding, redirects, digest handling, and extraction safety. This inventory is bounded, and inspected mocked network tests do not establish live service behavior.
- The configured test stack includes pytest, pytest-mock, randomly, rerunfailures, timeout, xdist, and subprocess coverage support; tox packages a wheel and runs coverage-driven pytest with parallel workers by default.
- tests/conftest.py gates integration tests on --int and slow tests on --skip-slow, except its single-item early return; property tests are excluded by default and run through a dedicated tox environment.
- CLI tests assert help/version exits, logging setup behavior, and diagnostics for an unavailable discovery method; discovery tests exercise missing-candidate fallback, env/CLI ordering, and an absolute target overriding try-first hints.
- test_app_data_pinning creates an environment with local pip 26.0.1 and checks pip list output; acquisition tests assert a second exact-version request reuses cached download history.
- Cached-seeder tests run two simultaneous environment creations, aggregate injected image-build failures, and assert extraction rejects parent traversal and POSIX/Windows absolute archive entries.
- Hypothesis properties assert pyvenv.cfg never invents keys and retains one line per key, while batch quoting properties cover dangerous syntax, line boundaries, literal percent signs, and preserved parentheses.
- Digest/TLS tests mock urlopen to cover matching and mismatching hashes, missing digests, retries, and insecure fallback opt-in; redirect tests cover auto/forced/disabled behavior and preserving foreign, undecodable, or directory targets.
- Inspected CI defines OS/interpreter matrices, separate property/fuzz/tasks/type/zipapp jobs, combined coverage, and CodeQL/query tests; configured coverage fails below 76% and omits runtime activation/import-hook files, so these definitions are neither execution results nor exhaustive coverage.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. The important boundaries involve executing trusted interpreters/plugins, downloading executable packages, generating shell/configuration text, and deleting or overwriting filesystem state. Controls include strict download arguments, digest checks, extraction containment, and quoted substitutions. Cache reuse and subprocess environment handling deserve focused review because their behavior spans multiple invocations and processes.
- Registered entry points are loaded through e.load before implementation selection; the threat model explicitly trusts installed plugins and target interpreters running with the invoking user's rights.
- Filesystem effects extend beyond repository scope: --clear deletes the validated destination, --reset-app-data deletes the selected cache, default cache setup can migrate an old folder, and creation may write an adjacent .venv redirect.
- Download arguments are allow-listed, but PyPI digest verification is skipped when PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, or PIP_INDEX is nonempty; the heuristic explicitly does not inspect pip.conf, and local extra-search wheels are trusted without hashes.
- VIRTUALENV_PERIODIC_UPDATE_INSECURE enables an unverified TLS context after the normal metadata lookup fails; those metadata responses provide the expected downloaded-wheel SHA-256 and release dates.
- Downloaded wheels and installation images are reused from trusted app-data without re-verification; bundled verification is memoized by filename, and has_image accepts any nonempty image directory.
- PipInvoke debug logging formats the full subprocess environment through LogCmd; trigger_update launches without its supplied env mapping, and _run_do_update uses os.environ rather than that caller mapping.
- Hypothesis: an interrupted image build or concurrent update-log writer can leave partial/shared state because image validity is only nonemptiness, JSON writes replace contents directly, and inspected update callers do not enter the store's available lock context. (inferred)
- Hypothesis: attacker-modified existing distribution metadata could expand reseeding's deletion scope, since _uninstall_dist joins top_level.txt and RECORD paths to dist.parent and deletes them without an explicit containment check in this function; the documented model trusts destination files. (inferred)
Extension points
Installed Python entry points form the principal extension mechanism. Each stage has a selection adapter and an implementation interface, with interpreter capabilities constraining applicable choices. Creation can extend filesystem references and layouts, while seeding can replace installation strategy. Activators pair shell-specific classes with templates, and storage/build hooks provide additional internal seams.
- Plugins register under virtualenv.discovery, virtualenv.create, virtualenv.seed, or virtualenv.activate; installed metadata supplies CLI choices, and built-in entry-point values win duplicate names.
- Discovery plugins implement Discover.run and add_parser_arguments, consume VirtualEnvOptions, and expose a lazily cached interpreter; get_discover installs their CLI options before construction.
- Creator plugins provide can_create metadata, add_parser_arguments, and create; CreatorSelector rejects the reserved builtin registration name, reports capability errors, and passes selected metadata into construction.
- Builtin creator families extend sources, setup_meta, and _executables; PathRefToDest maps host resources to destinations, while ExePathRefToDest handles executable aliases and copy/link differences.
- Describe supplies interpreter-derived layout properties and can_describe; non-Describe creators receive a compatible describer, and Venv delegates noncallable layout attributes to it.
- SeederSelector constructs selected seeders and checks cannot_seed only when enabled; BaseEmbed exposes distribution_to_versions, and FromAppData selects CopyPipInstall or SymlinkPipInstall strategies.
- Activator extensions participate through supports, add_parser_arguments, and generation; ViaTemplateActivator offers templates, quote, replacements, substitutions, and as_name overrides, illustrated by BashActivator's activate.sh → activate mapping.
- Internal factory seams include make_app_data's disk/read-only/temporary selection and the Hatch custom build hook; ReadOnlyAppData disables updates and overrides cache writes, while SbomBuildHook appends generated SBOM files only for supported wheel builds.
Contributor handoff
Start with orchestration and the selected implementation rather than assuming the inventory reflects current ownership. Tests and CI were inspected, not executed, and the brief covers a bounded set of source paths. Preserve option provenance, cache/version boundaries, shell quoting, and platform-specific layout behavior when making changes. Execution, installation, and release commands require a later task that authorizes them.
- Read pyproject.toml, run/__init__.py, Session, and plugin selectors first: options are introduced through staged parsing, and creator, seeder, and activator objects are constructed only after final parsing.
- For discovery work, distinguish local adaptation from external implementation: Builtin forwards to python-discovery, and discovery/py_info.py only re-exports PythonInfo.
- Do not treat session_via_cli as side-effect-free: it calls build_parser, which constructs app-data defaults and handles reset/upgrade commands; make_app_data can create or migrate cache directories.
- Preserve provenance-aware precedence when changing flags: CLI outranks env, env outranks INI, and copy wins same-level conflicts; negative tri-state flags have special default handling.
- For seeding edits, read BaseEmbed, acquisition, bundle selection, image installer, and embedded metadata together; preserve the >=3.12 setuptools default, wheel no-op deprecation, hash table, and target-version rejection.
- For generated-file edits, preserve single-pass quoted template substitution and line-boundary collapse in pyvenv.cfg; retain the Python <3.10 import-hook gate and guarded foreign-redirect handling.
- Tests and CI were inspected, not executed. In a later execution-authorized task, use an existing tox interpreter environment with a focused pytest path first, add --int for integration selection, and use separate property/tasks environments; configured CI jobs and thresholds are not passing results.
- Follow complete parameter/return annotations and future annotations, Ruff's 120-column configuration, and allowed Towncrier fragment types; distinguish verification from tox fix, whose pre-commit hooks can modify files with unsafe fixes.
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 182 | 95% |
| YAML | 21 | docs/config |
| JSON | 9 | docs/config |
| Markdown | 9 | docs/config |
| TOML | 4 | 2% |
| C | 2 | 1% |
| JavaScript | 2 | 1% |
| CSS | 1 | docs/config |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (104 files)
Source layout — src/
| Path | Files |
|---|---|
src/virtualenv/ | 104 |
Repository structure
| Top-level path | Files |
|---|---|
src/ | 104 |
tests/ | 77 |
.github/ | 36 |
docs/ | 27 |
tasks/ | 20 |
Docs found: README.md
Package
pyproject.toml — virtualenv vvcs, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme
Structural health signals
Average score 8/10 across 96 analyzed source files; 6 hotspots surfaced.
hatch_build.py— 641 lines, score 5.9 (Large file, Deep nesting)tasks/upgrade_wheels.py— 350 lines, score 5.9 (Deep nesting, High churn)src/virtualenv/create/via_global_ref/builtin/cpython/mac_os.py— 290 lines, score 5.9 (Deep nesting, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
571bc2041dae2026-10-02 — release 21.14.55b9b7de4f2f82026-10-03 — Reset the embed update log when it cannot be read (#3376)9fd48c89ad692026-10-02 — 🐛 fix(ci): dump stacks from a thread that holds the GIL (#3377)5183a1066e582026-10-02 — 🎨 style: give every Final annotation its type (#3375)288f13c7ae4f2026-10-02 — 🎨 style(test): mark prompt fixture locals Final (#3374)