CLI interface

CLI flags

virtualenv is primarily a command line application.

It modifies the environment variables in a shell to create an isolated Python environment, so you’ll need to have a shell to run it. You can type in virtualenv (name of the application) followed by flags that control its behaviour. All options have sensible defaults, and there’s one required argument: the name/path of the virtual environment to create. The default values for the command line options can be overridden via the Configuration file or Environment Variables. Environment variables takes priority over the configuration file values (--help will show if a default comes from the environment variable as the help message will end in this case with environment variables or the configuration file).

The options that can be passed to virtualenv, along with their default values and a short description are listed below.

virtualenv [OPTIONS]

Named Arguments
--version		display the version of the virtualenv package and its location, then exit
--with-traceback	False	on failure also display the stacktrace internals of virtualenv
--read-only-app-data	False	use app data folder in read-only mode (write operations will fail with error)
--app-data	platform specific application data folder	a data folder used as cache by the virtualenv
--reset-app-data	False	start with empty app data folder
--upgrade-embed-wheels	False	trigger a manual update of the embedded wheels

verbosity ⇒ verbosity = verbose - quiet, default INFO, mapping => CRITICAL=0, ERROR=1, WARNING=2, INFO=3, DEBUG=4, NOTSET=5
-v, --verbose	2	increase verbosity
-q, --quiet	0	decrease verbosity

discovery

core ⇒ options shared across all discovery
--discovery	builtin	interpreter discovery method; choice of: builtin
-p, --python	the python executable virtualenv is installed into	interpreter based on what to create environment (path/identifier) - by default use the interpreter where the tool is installed - first found wins
--try-first-with	[]	try first these interpreters before starting the discovery

creator

core ⇒ options shared across all creator
--creator	builtin if exist, else venv	create environment via; choice of: cpython3-mac-brew, cpython3-mac-framework, cpython3-posix, cpython3-win, pypy3-posix, pypy3-win, venv
dest		directory to create virtualenv at
--clear	False	remove the destination directory if exist before starting (will overwrite files otherwise)
--no-vcs-ignore	False	don’t create VCS ignore directive in the destination directory
--system-site-packages	False	give the virtual environment access to the system site-packages dir
--symlinks	True	try to use symlinks rather than copies, when symlinks are not the default for the platform
--copies, --always-copy	False	try to use copies rather than symlinks, even when symlinks are the default for the platform

seeder

core ⇒ options shared across all seeder
--seeder	app-data	seed packages install method; choice of: app-data, pip
--no-seed, --without-pip	False	do not install seed packages
--no-download, --never-download	True	pass to disable download of the latest pip/setuptools/wheel from PyPI
--download	False	pass to enable download of the latest pip/setuptools/wheel from PyPI
--extra-search-dir	[]	a path containing wheels to extend the internal wheel list (can be set 1+ times)
--pip	bundle	version of pip to install as seed: embed, bundle, none or exact version
--setuptools	bundle	version of setuptools to install as seed: embed, bundle, none or exact version
--wheel	bundle	version of wheel to install as seed: embed, bundle, none or exact version
--no-pip	False	do not install pip
--no-setuptools	False	do not install setuptools
--no-wheel	False	do not install wheel
--no-periodic-update	False	disable the periodic (once every 14 days) update of the embedded wheels

app-data ⇒ options specific to seeder app-data
--symlink-app-data	False	symlink the python packages from the app-data folder (requires seed pip>=19.3)

activators

core ⇒ options shared across all activators
--activators	comma separated list of activators supported	activators to generate - default is all supported; choice of: bash, batch, cshell, fish, nushell, powershell, python
--prompt		provides an alternative prompt prefix for this environment (value of . means name of the current working directory)

Defaults

Configuration file

Unless VIRTUALENV_CONFIG_FILE is set, virtualenv looks for a standard virtualenv.ini configuration file. The exact location depends on the operating system you’re using, as determined by platformdirs application configuration definition. It can be overridden by setting the VIRTUALENV_CONFIG_FILE environment variable. The configuration file location is printed as at the end of the output when --help is passed.

The keys of the settings are derived from the command line option (left strip the - characters, and replace - with _). Where multiple flags are available first found wins (where order is as it shows up under the --help).

For example, --python would be specified as:

[virtualenv]
python = /opt/python-3.8/bin/python

Options that take multiple values, like extra-search-dir can be specified as:

[virtualenv]
extra_search_dir =
    /path/to/dists
    /path/to/other/dists

Environment Variables

Default values may be also specified via environment variables. The keys of the settings are derived from the command line option (left strip the - characters, and replace - with _, finally capitalize the name). Where multiple flags are available first found wins (where order is as it shows up under the --help).

For example, to use a custom Python binary, instead of the one virtualenv is run with, you can set the environment variable VIRTUALENV_PYTHON like:

env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python virtualenv

Where the option accepts multiple values, for example for python or extra-search-dir, the values can be separated either by literal newlines or commas. Newlines and commas can not be mixed and if both are present only the newline is used for separating values. Examples for multiple values:

env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python,python3.8 virtualenv
env VIRTUALENV_EXTRA_SEARCH_DIR=/path/to/dists\n/path/to/other/dists virtualenv

The equivalent CLI-flags based invocation for the above examples would be:

virtualenv --python=/opt/python-3.8/bin/python --python=python3.8
virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists