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