Plugin API reference¶

This page documents the interfaces that plugins must implement.

Discovery¶

Discovery plugins locate Python interpreters for creating virtual environments.

class virtualenv.discovery.discover.Discover(options)¶

Discover and provide the requested Python interpreter.

Parameters:: options (VirtualEnvOptions)

Create a new discovery mechanism.

Parameters:: options (VirtualEnvOptions) – the parsed options as defined within add_parser_arguments()

classmethod add_parser_arguments(parser)¶

Add CLI arguments for this discovery mechanisms.

Parameters:: parser (ArgumentParser) – the CLI parser
Return type:: None

abstractmethod run()¶

Discovers an interpreter.

Return type:: PythonInfo | None
Returns:: the interpreter ready to use for virtual environment creation

property interpreter: PythonInfo | None¶

Returns:: the interpreter as returned by run(), cached

PythonInfo¶

Discovery plugins return a PythonInfo object describing the located interpreter.

class virtualenv.discovery.py_info.PythonInfo¶

Contains information for a Python interpreter.

install_path(key)¶

Return the relative installation path for a given installation scheme key.

Parameters:: key (str) – the sysconfig scheme key (e.g. purelib, headers)
Return type:: str
Returns:: the relative path for the given key

property version_str: str¶: The full version as major.minor.micro string (e.g. 3.13.2).

property version_release_str: str¶: The release version as major.minor string (e.g. 3.13).

property python_name: str¶: The python executable name as pythonX.Y (e.g. python3.13).

property is_old_virtualenv: bool¶: True if this interpreter runs inside an old-style virtualenv (has real_prefix).

property is_venv: bool¶: True if this interpreter runs inside a PEP 405 venv (has base_prefix).

sysconfig_path(key, config_var=None, sep='/')¶

Return the sysconfig install path for a scheme key, optionally substituting config variables.

Parameters:

key (str) – the sysconfig path name (e.g. stdlib, purelib)
config_var (dict[str, str] | None) – override config variables for path expansion, or None to use defaults
sep (str) – path separator to use

Return type:

str

Returns:

the expanded path string

creators(refresh=False)¶

Return the available creators for this interpreter, cached unless refresh is True.

Parameters:: refresh (bool) – if True, re-discover creators instead of using the cache
Return type:: CreatorSelector
Returns:: the creator selector for this interpreter

property system_include: str¶: The path to the system include directory for C headers.

property system_prefix: str¶: The prefix of the system Python this interpreter is based on.

property system_exec_prefix: str¶: The exec prefix of the system Python this interpreter is based on.

property machine: str¶

The instruction set architecture (ISA) of this interpreter.

Derived from sysconfig.get_platform(), which returns the platform identity string used by Python’s build system (e.g. macosx-14.0-arm64, linux-x86_64, win-amd64). The ISA is the last component of this string.

For macOS universal2 fat binaries, falls back to platform.machine() to report the actual runtime ISA (arm64 or x86_64) rather than the build target.

Returns:: the ISA string, e.g. arm64, x86_64, x86

property spec: str¶: A specification string identifying this interpreter (e.g. CPython3.13.2-64-arm64).

classmethod clear_cache(app_data)¶

Clear all cached interpreter information from the application data store.

Parameters:: app_data (AppData) – the application data store to clear
Return type:: None

satisfies(spec, impl_must_match)¶

Check if a given specification can be satisfied by this python interpreter instance.

Parameters:

spec (PythonSpec) – the python specification to check against
impl_must_match (bool) – if True, the implementation (e.g. CPython vs PyPy) must also match

Return type:

bool

Returns:

True if this interpreter satisfies the specification

classmethod current(app_data=None)¶

Locate the current host interpreter information.

This might differ from the running interpreter if the host Python has been upgraded.

Parameters:: app_data (AppData | None) – the application data store for caching
Return type:: PythonInfo
Returns:: the current interpreter information

classmethod current_system(app_data=None)¶

Locate the current system interpreter information, resolving through any virtualenv layers.

Parameters:: app_data (AppData | None) – the application data store for caching
Return type:: PythonInfo
Returns:: the system interpreter information

classmethod from_exe(exe, app_data=None, raise_on_error=True, ignore_cache=False, resolve_to_host=True, env=None)¶

Given a path to an executable, get the python information.

Parameters:

exe (str) – path to the Python executable
app_data (AppData | None) – the application data store for caching
raise_on_error (bool) – if True, raise on failure instead of returning None
ignore_cache (bool) – if True, bypass the cache and re-query the interpreter
resolve_to_host (bool) – if True, resolve through virtualenv layers to the host interpreter
env (Mapping[str, str] | None) – environment variables to use for subprocess calls

Return type:

PythonInfo | None

Returns:

the interpreter information, or None if discovery failed and raise_on_error is False

discover_exe(app_data, prefix, exact=True, env=None)¶

Discover a matching Python executable under a given prefix directory.

Parameters:

app_data (AppData) – the application data store for caching
prefix (str) – the directory prefix to search under
exact (bool) – if True, require an exact version match; if False, pick the closest match
env (Mapping[str, str] | None) – environment variables to use for subprocess calls

Return type:

PythonInfo

Returns:

the discovered interpreter information

App data¶

The application data interface used by plugins for caching.

class virtualenv.app_data.base.AppData¶

Abstract storage interface for the virtualenv application.

abstractmethod close()¶

Called before virtualenv exits.

Return type:: None

abstractmethod reset()¶

Called when the user passes in the reset app data.

Return type:: None

abstractmethod py_info(path)¶

Return a content store for cached interpreter information at the given path.

Parameters:: path (Path) – the interpreter executable path
Return type:: ContentStore
Returns:: a content store for the cached data

abstractmethod py_info_clear()¶

Clear all cached interpreter information.

Return type:: None

property can_update: bool¶: True if this app data store supports updating cached content.

abstractmethod embed_update_log(distribution, for_py_version)¶

Return a content store for the embed update log of a distribution.

Parameters:

distribution (str) – the package name (e.g. pip)
for_py_version (str) – the target Python version string

Return type:

ContentStore

Returns:

a content store for the update log

property house: Path¶: The root directory of the application data store.

property transient: bool¶: True if this app data store is transient and does not persist across runs.

abstractmethod wheel_image(for_py_version, name)¶

Return the path to a cached wheel image.

Parameters:

for_py_version (str) – the target Python version string
name (str) – the package name

Return type:

Path

Returns:

the path to the cached wheel

ensure_extracted(path, to_folder=None)¶

Ensure a path is available on disk, extracting from zipapp if needed.

Parameters:

path (Path) – the path to ensure is available
to_folder (Path | None) – optional target directory for extraction

Return type:

Generator[Path]

Returns:

yields the usable path on disk

abstractmethod extract(path, to_folder)¶

Extract a path from the zipapp to a location on disk.

Parameters:

path (Path) – the path to extract
to_folder (Path | None) – optional target directory

Return type:

Generator[Path]

Returns:

yields the extracted path

abstractmethod locked(path)¶

Acquire an exclusive lock on the given path.

Parameters:: path (Path) – the path to lock
Return type:: Generator[None]

Creators¶

Creator plugins build the virtual environment directory structure and install the Python interpreter.

class virtualenv.create.creator.CreatorMeta¶

class virtualenv.create.creator.Creator(options, interpreter)¶

A class that given a python Interpreter creates a virtual environment.

Parameters:

options (VirtualEnvOptions)
interpreter (PythonInfo)

Construct a new virtual environment creator.

Parameters:

options (VirtualEnvOptions) – the CLI option as parsed from add_parser_arguments()
interpreter (PythonInfo) – the interpreter to create virtual environment from

classmethod can_create(interpreter)¶

Determine if we can create a virtual environment.

Parameters:: interpreter (PythonInfo) – the interpreter in question
Return type:: CreatorMeta | None
Returns:: None if we can’t create, any other object otherwise that will be forwarded to add_parser_arguments()

classmethod add_parser_arguments(parser, interpreter, meta, app_data)¶

Add CLI arguments for the creator.

Parameters:

parser (ArgumentParser) – the CLI parser
app_data (AppData) – the application data folder
interpreter (PythonInfo) – the interpreter we’re asked to create virtual environment for
meta (CreatorMeta) – value as returned by can_create()

Return type:

None

abstractmethod create()¶

Perform the virtual environment creation.

Return type:: None

add_cachedir_tag()¶: Generate a file indicating that this is not meant to be backed up.

setup_ignore_vcs()¶: Generate ignore instructions for version control systems.

Seeders¶

Seeder plugins install initial packages (like pip, setuptools, wheel) into the virtual environment.

class virtualenv.seed.seeder.Seeder(options, enabled)¶

A seeder will install some seed packages into a virtual environment.

Parameters:

options (VirtualEnvOptions)
enabled (bool)

Create.

Parameters:

options (VirtualEnvOptions) – the parsed options as defined within add_parser_arguments()
enabled (bool) – a flag weather the seeder is enabled or not

classmethod add_parser_arguments(parser, interpreter, app_data)¶

Add CLI arguments for this seed mechanisms.

Parameters:

parser (ArgumentParser) – the CLI parser
app_data (AppData) – the CLI parser
interpreter (PythonInfo) – the interpreter this virtual environment is based of

Return type:

None

abstractmethod run(creator)¶

Perform the seed operation.

Parameters:: creator (Creator) – the creator (based of virtualenv.create.creator.Creator) we used to create this virtual environment
Return type:: None

Activators¶

Activator plugins generate shell-specific activation scripts.

class virtualenv.activation.activator.Activator(options)¶

Generates activate script for the virtual environment.

Parameters:: options (VirtualEnvOptions)

Create a new activator generator.

Parameters:: options (VirtualEnvOptions) – the parsed options as defined within add_parser_arguments()

classmethod supports(interpreter)¶

Check if the activation script is supported in the given interpreter.

Parameters:: interpreter (PythonInfo) – the interpreter we need to support
Return type:: bool
Returns:: True if supported, False otherwise

classmethod add_parser_arguments(parser, interpreter)¶

Add CLI arguments for this activation script.

Parameters:

parser (ArgumentParser) – the CLI parser
interpreter (PythonInfo) – the interpreter this virtual environment is based of

Return type:

None

abstractmethod generate(creator)¶

Generate activate script for the given creator.

Parameters:: creator (Creator) – the creator (based of virtualenv.create.creator.Creator) we used to create this virtual environment
Return type:: list[Path]