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: then 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 it’s location, then exit

--with-traceback

False

on failure also display the stacktrace internals of virtualenv

--app-data

platform specific application data folder

a data folder used as cache by the virtualenv

--clear-app-data

False

start with empty app data folder

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-mac-framework, cpython2-posix, cpython2-win, cpython3-posix, cpython3-win, pypy2-posix, pypy2-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)

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

--symlink-app-data

False

not supported - 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, 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 configuration 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.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

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