# Behavior traces — pypa/virtualenv

> Canonical page: https://codevetter.com/unpack/virtualenv/behavior-traces

# Behavior traces — pypa/virtualenv

Scanned commit 571bc2041dae5ecbd250d82ec7ef482cfd3c3b69 (2026-10-02). Generated by codevetter codevetter 1.15.0 on 2026-10-02.

Source inspection; upstream code and tests were not executed.

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. — [src/virtualenv/__main__.py#L19-L31](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/__main__.py#L19-L31) [src/virtualenv/__main__.py#L71-L83](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/__main__.py#L71-L83) [src/virtualenv/run/__init__.py#L43-L75](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L43-L75) [src/virtualenv/run/__init__.py#L91-L118](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L91-L118)
- 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. — [src/virtualenv/run/plugin/discovery.py#L37-L50](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/plugin/discovery.py#L37-L50) [src/virtualenv/discovery/discover.py#L32-L38](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/discovery/discover.py#L32-L38) [src/virtualenv/discovery/builtin.py#L21-L28](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/discovery/builtin.py#L21-L28) [src/virtualenv/run/__init__.py#L104-L108](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L104-L108)
- 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. — [src/virtualenv/run/session.py#L76-L80](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/session.py#L76-L80) [src/virtualenv/create/creator.py#L217-L227](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/creator.py#L217-L227) [src/virtualenv/create/via_global_ref/builtin/via_global_self_do.py#L88-L111](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/via_global_ref/builtin/via_global_self_do.py#L88-L111) [src/virtualenv/create/via_global_ref/api.py#L110-L126](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/via_global_ref/api.py#L110-L126)
- 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. — [src/virtualenv/create/via_global_ref/venv.py#L26-L32](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/via_global_ref/venv.py#L26-L32) [src/virtualenv/create/via_global_ref/venv.py#L50-L86](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/via_global_ref/venv.py#L50-L86)
- 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. — [src/virtualenv/run/session.py#L82-L85](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/session.py#L82-L85) [src/virtualenv/seed/embed/via_app_data/via_app_data.py#L56-L61](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/via_app_data.py#L56-L61) [src/virtualenv/seed/embed/via_app_data/via_app_data.py#L87-L143](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/via_app_data.py#L87-L143)
- 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. — [src/virtualenv/seed/embed/via_app_data/via_app_data.py#L145-L159](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/via_app_data.py#L145-L159) [src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L57-L89](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L57-L89) [src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L108-L129](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L108-L129) [src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L179-L185](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/via_app_data/pip_install/base.py#L179-L185)
- 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. — [src/virtualenv/run/session.py#L87-L92](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/session.py#L87-L92) [src/virtualenv/activation/bash/__init__.py#L14-L27](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/activation/bash/__init__.py#L14-L27) [src/virtualenv/activation/via_template.py#L44-L77](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/activation/via_template.py#L44-L77) [src/virtualenv/activation/bash/activate.sh#L10-L96](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/activation/bash/activate.sh#L10-L96)
- 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. — [src/virtualenv/seed/wheels/bundle.py#L29-L33](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/wheels/bundle.py#L29-L33) [src/virtualenv/seed/wheels/periodic_update.py#L80-L94](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/wheels/periodic_update.py#L80-L94) [src/virtualenv/seed/wheels/periodic_update.py#L228-L269](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/wheels/periodic_update.py#L228-L269) [src/virtualenv/run/__init__.py#L100-L129](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L100-L129)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)