Python

The primary interface to virtualenv is the command line application. However, it can also be used programmatically via the virtualenv.cli_run function and the Session class.

See Use virtualenv for usage examples.

virtualenv module

virtualenv.cli_run(args, options=None, setup_logging=True, env=None)

Create a virtual environment given some command line interface arguments.

Parameters:

  • args (list[str]) – the command line arguments

  • options (VirtualEnvOptions | None) – passing in a VirtualEnvOptions object allows return of the parsed options

  • setup_logging (bool) – True if setup logging handlers, False to use handlers already registered

  • env (MutableMapping[str, str] | None) – environment variables to use

Return type:

Session

Returns:

the session object of the creation (its structure for now is experimental and might change on short notice)

virtualenv.session_via_cli(args, options=None, setup_logging=True, env=None)

Create a virtualenv session (same as cli_run, but this does not perform the creation). Use this if you just want to query what the virtual environment would look like, but not actually create it.

Parameters:

  • args (list[str]) – the command line arguments

  • options (VirtualEnvOptions | None) – passing in a VirtualEnvOptions object allows return of the parsed options

  • setup_logging (bool) – True if setup logging handlers, False to use handlers already registered

  • env (MutableMapping[str, str] | None) – environment variables to use

Return type:

Session

Returns:

the session object of the creation (its structure for now is experimental and might change on short notice)

Session class

The Session class represents a virtualenv creation session and provides access to the created environment’s properties.

class virtualenv.run.session.Session(verbosity, app_data, interpreter, creator, seeder, activators)

Represents a virtual environment creation session.

Parameters:
property verbosity: int

The verbosity of the run.

property interpreter: PythonInfo

Create a virtual environment based on this reference interpreter.

property creator: Creator

The creator used to build the virtual environment (must be compatible with the interpreter).

property seeder: Seeder

The mechanism used to provide the seed packages (pip, setuptools, wheel).

property activators: list[Activator]

Activators used to generate activations scripts.

VirtualEnvOptions

Options namespace passed to plugin constructors, populated from the CLI, environment variables, and configuration files.

class virtualenv.config.cli.parser.VirtualEnvOptions(**kwargs)
Parameters:

kwargs (Any)

set_src(key, value, src)

Set an option value and record where it came from.

Parameters:

  • key (str) – the option name

  • value (Any) – the option value

  • src (str) – the source of the value (e.g. "cli", "env var", "default")

Return type:

None

get_source(key)

Return the source that provided a given option value.

Parameters:

key (str) – the option name

Return type:

str | None

Returns:

the source string (e.g. "cli", "env var", "default"), or None if not tracked

property verbosity: int | None

The verbosity level, computed as verbose - quiet, clamped to zero.

Returns:

the verbosity level, or None if neither --verbose nor --quiet has been parsed yet