# Feature catalog — pypa/virtualenv

> Canonical page: https://codevetter.com/unpack/virtualenv/feature-catalog

# Feature catalog — 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.

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. — [src/virtualenv/discovery/builtin.py#L36-L76](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/discovery/builtin.py#L36-L76) [docs/how-to/usage.rst#L23-L80](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/docs/how-to/usage.rst#L23-L80)
- Creation options include --creator, --copies/--always-copy, --symlinks, --system-site-packages, --clear, and --no-vcs-ignore; unsupported copy/link capabilities constrain available flags. — [src/virtualenv/run/plugin/creators.py#L66-L76](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/plugin/creators.py#L66-L76) [src/virtualenv/create/via_global_ref/api.py#L71-L108](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/via_global_ref/api.py#L71-L108) [src/virtualenv/create/creator.py#L125-L143](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/creator.py#L125-L143)
- --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. — [src/virtualenv/run/plugin/seeders.py#L21-L39](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/plugin/seeders.py#L21-L39) [src/virtualenv/seed/embed/base_embed.py#L92-L148](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/base_embed.py#L92-L148) [pyproject.toml#L102-L103](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/pyproject.toml#L102-L103)
- 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. — [src/virtualenv/seed/embed/base_embed.py#L35-L49](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/base_embed.py#L35-L49) [src/virtualenv/seed/embed/base_embed.py#L70-L89](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/base_embed.py#L70-L89) [src/virtualenv/seed/embed/base_embed.py#L117-L140](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/embed/base_embed.py#L117-L140) [src/virtualenv/seed/wheels/embed/__init__.py#L11-L54](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/seed/wheels/embed/__init__.py#L11-L54)
- --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. — [pyproject.toml#L70-L77](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/pyproject.toml#L70-L77) [src/virtualenv/run/plugin/activators.py#L18-L69](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/plugin/activators.py#L18-L69)
- 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. — [src/virtualenv/config/env_var.py#L15-L33](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/config/env_var.py#L15-L33) [src/virtualenv/config/ini.py#L22-L47](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/config/ini.py#L22-L47) [src/virtualenv/run/__init__.py#L132-L162](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L132-L162)
- cli_run creates and returns a Session; session_via_cli constructs the session without running creation, exposing creator, interpreter, seeder, and activators for callers. — [src/virtualenv/run/__init__.py#L26-L82](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L26-L82) [src/virtualenv/run/session.py#L45-L68](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/session.py#L45-L68) [docs/reference/api.rst#L7-L24](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/docs/reference/api.rst#L7-L24)
- 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. — [src/virtualenv/create/creator.py#L229-L263](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/creator.py#L229-L263) [src/virtualenv/create/creator.py#L270-L288](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/create/creator.py#L270-L288) [src/virtualenv/run/__init__.py#L165-L191](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/run/__init__.py#L165-L191) [src/virtualenv/__main__.py#L53-L91](https://github.com/pypa/virtualenv/blob/571bc2041dae5ecbd250d82ec7ef482cfd3c3b69/src/virtualenv/__main__.py#L53-L91)

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)