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


display the version of the virtualenv package and it’s location, then exit



on failure also display the stacktrace internals of virtualenv


platform specific application data folder

a data folder used as cache by the virtualenv



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


increase verbosity

-q, --quiet


decrease verbosity


core ⇒ options shared across all discovery



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)


core ⇒ options shared across all creator


builtin if exist, else venv

create environment via; choice of: cpython2-mac-framework, cpython2-posix, cpython2-win, cpython3-mac-framework, cpython3-posix, cpython3-win, pypy2-posix, pypy2-win, pypy3-posix, pypy3-win, venv


directory to create virtualenv at



remove the destination directory if exist before starting (will overwrite files otherwise)



give the virtual environment access to the system site-packages dir



try to use symlinks rather than copies, when symlinks are not the default for the platform

--copies, --always-copy


try to use copies rather than symlinks, even when symlinks are the default for the platform


core ⇒ options shared across all seeder



seed packages install method; choice of: app-data, pip

--no-seed, --without-pip


do not install seed packages



pass to enable download of the latest pip/setuptools/wheel from PyPI

--no-download, --never-download


pass to disable download of the latest pip/setuptools/wheel from PyPI



a path containing wheels the seeder may also use beside bundled (can be set 1+ times)



pip version to install, bundle for bundled



setuptools version to install, bundle for bundled



wheel version to install, bundle for bundled



do not install pip



do not install setuptools



do not install wheel

app-data ⇒ options specific to seeder app-data



symlink the python packages from the app-data folder (requires seed pip>=19.3)


core ⇒ options shared across all activators


comma separated list of activators supported

activators to generate - default is all supported; choice of: bash, batch, cshell, fish, powershell, python, xonsh


provides an alternative prompt prefix for this environment


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:

python = /opt/python-3.8/bin/python

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

extra-search-dir =

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