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, so you’ll get a working virtual environment in a venv folder even if you don’t pass any options. 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 it’s location, then exit

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	target interpreter for which to create a virtual (either absolute path or identifier string)

creator¶

core ⇒ options shared across all creator
`--creator`	`builtin` if exist, else `venv`	create environment via; choice of: `cpython2-posix`, `cpython2-win`, `cpython3-posix`, `cpython3-win`, `pypy2-posix`, `pypy2-win`, `pypy3-posix`, `pypy3-win`, `venv`
`dest`	`venv`	directory to create virtualenv at
`--clear`	`False`	remove the destination directory if exist before starting (will overwrite files otherwise)
`--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
`--download`	`False`	pass to enable download of the latest pip/setuptools/wheel from PyPI
`--no-download`, `--never-download`	`True`	pass to disable download of the latest pip/setuptools/wheel from PyPI
`--extra-search-dir`	`[]`	a path containing wheels the seeder may also use beside bundled (can be set 1+ times)
`--pip`	`latest`	pip version to install, `bundle` for bundled
`--setuptools`	`latest`	setuptools version to install, `bundle` for bundled
`--wheel`	`latest`	wheel version to install, `bundle` for bundled
`--no-pip`	`False`	do not install pip
`--no-setuptools`	`False`	do not install setuptools
`--no-wheel`	`False`	do not install wheel

app-data ⇒ options specific to seeder app-data
`--clear-app-data`	`False`	clear the app data folder of seed images

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`, `powershell`, `python`, `xonsh`
`--prompt`		provides an alternative prompt prefix for this environment

Defaults¶

Configuration file¶

virtualenv looks for a standard ini configuration file. The exact location depends on the operating system you’re using, as determined by appdirs application data definition. 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 long command line option. For example, --python would be specified as:

[virtualenv]
python = /opt/python-3.3/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¶

Each command line option has a corresponding environment variables with the name format VIRTUALENV_<UPPER_NAME>. The UPPER_NAME is the name of the command line options capitalized and dashes ('-') replaced with underscores ('_').

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

This also works for appending command line options, like extra-search-dir, where a literal newline is used to separate the values:

env VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists\n/path/to/other/dists" virtualenv

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

virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists