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)
Parameters:

options (VirtualEnvOptions) –

classmethod add_parser_arguments(parser)
Parameters:

parser (ArgumentParser) –

Return type:

None

abstract run()
Return type:

Optional[PythonInfo]

property interpreter: python_discovery._py_info.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) – sysconfig installation scheme key (e.g. "scripts", "purelib").

Return type:

str

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) – sysconfig path key (e.g. "purelib", "include").

  • config_var (Optional[dict[str, str]]) – replacement mapping for sysconfig variables; when None uses the interpreter’s own values.

  • sep (str) – path separator to use in the result.

Return type:

str

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

Return the instruction set architecture (ISA) derived from sysconfig.get_platform().

property spec: str

A specification string identifying this interpreter (e.g. CPython3.13.2-64-arm64).

classmethod clear_cache(cache)

Clear all cached interpreter information from cache.

Parameters:

cache (PyInfoCache) – the cache 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 specification to check against.

  • impl_must_match (bool) – when True, the implementation name must match exactly.

Return type:

bool

classmethod current(cache=None)

Locate the current host interpreter information.

Parameters:

cache (Optional[PyInfoCache]) – interpreter metadata cache; when None results are not cached.

Return type:

PythonInfo

classmethod current_system(cache=None)

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

Parameters:

cache (Optional[PyInfoCache]) – interpreter metadata cache; when None results are not cached.

Return type:

PythonInfo

to_json()

Serialize this interpreter information to a JSON string.

Return type:

str

to_dict()

Convert this interpreter information to a plain dictionary.

Return type:

dict[str, object]

classmethod from_exe(exe, cache=None, *, raise_on_error=True, ignore_cache=False, resolve_to_host=True, env=None)

Get the python information for a given executable path.

Parameters:

  • exe (str) – path to the Python executable.

  • cache (Optional[PyInfoCache]) – interpreter metadata cache; when None results are not cached.

  • raise_on_error (bool) – raise on failure instead of returning None.

  • ignore_cache (bool) – bypass the cache and re-query the interpreter.

  • resolve_to_host (bool) – resolve through virtualenv layers to the system interpreter.

  • env (Optional[Mapping[str, str]]) – environment mapping; defaults to os.environ.

Return type:

Optional[PythonInfo]

classmethod from_json(payload)

Deserialize interpreter information from a JSON string.

Parameters:

payload (str) – JSON produced by to_json().

Return type:

PythonInfo

classmethod from_dict(data)

Reconstruct a PythonInfo from a plain dictionary.

Parameters:

data (dict[str, object]) – dictionary produced by to_dict().

Return type:

PythonInfo

classmethod resolve_to_system(cache, target)

Walk virtualenv/venv prefix chains to find the underlying system interpreter.

Parameters:

  • cache (Optional[PyInfoCache]) – interpreter metadata cache; when None results are not cached.

  • target (PythonInfo) – the interpreter to resolve.

Return type:

PythonInfo

discover_exe(cache, prefix, *, exact=True, env=None)

Discover a matching Python executable under a given prefix directory.

Parameters:

  • cache (PyInfoCache) – interpreter metadata cache.

  • prefix (str) – directory prefix to search under.

  • exact (bool) – when True, require an exact version match.

  • env (Optional[Mapping[str, str]]) – environment mapping; defaults to os.environ.

Return type:

PythonInfo

App data

The application data interface used by plugins for caching.

class virtualenv.app_data.base.AppData

Abstract storage interface for the virtualenv application.

abstract close()

Called before virtualenv exits.

Return type:

None

abstract reset()

Called when the user passes in the reset app data.

Return type:

None

abstract 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

abstract 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.

abstract 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.

abstract 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 (Optional[Path]) – optional target directory for extraction

Return type:

Generator[Path]

Returns:

yields the usable path on disk

abstract extract(path, to_folder)

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

Parameters:

  • path (Path) – the path to extract

  • to_folder (Optional[Path]) – optional target directory

Return type:

Generator[Path]

Returns:

yields the extracted path

abstract 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:

Construct a new virtual environment creator.

Parameters:
classmethod can_create(interpreter)

Determine if we can create a virtual environment.

Parameters:

interpreter (PythonInfo) – the interpreter in question

Return type:

Optional[CreatorMeta]

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

abstract 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.

Return type:

None

setup_ignore_vcs()

Generate ignore instructions for version control systems.

Return type:

None

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:

Create.

Parameters:
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

abstract 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

abstract 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]