CodeVetter · Repo Unpack · Feature catalog
pypa/virtualenv
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.