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
behavior. 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 |
||
'==SUPPRESS==' |
display the version of the virtualenv package and its location, then exit |
|
False |
on failure also display the stacktrace internals of virtualenv |
|
False |
use app data folder in read-only mode (write operations will fail with error) |
|
platform specific application data folder | a data folder used as cache by the virtualenv |
|
False |
start with empty app data folder |
|
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 |
||
2 |
increase verbosity |
|
0 |
decrease verbosity |
discovery¶
core ⇒ options shared across all discovery |
||
'builtin' |
interpreter discovery method; choice of: |
|
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 these interpreters before starting the discovery |
creator¶
core ⇒ options shared across all creator |
||
|
create environment via; choice of: |
|
directory to create virtualenv at |
||
False |
remove the destination directory if exist before starting (will overwrite files otherwise) |
|
False |
don’t create VCS ignore directive in the destination directory |
|
False |
give the virtual environment access to the system site-packages dir |
|
True |
try to use symlinks rather than copies, when symlinks are not the default for the platform |
|
False |
try to use copies rather than symlinks, even when symlinks are the default for the platform |
seeder¶
core ⇒ options shared across all seeder |
||
'app-data' |
seed packages install method; choice of: |
|
False |
do not install seed packages |
|
True |
pass to disable download of the latest pip/setuptools/wheel from PyPI |
|
False |
pass to enable download of the latest pip/setuptools/wheel from PyPI |
|
[] |
a path containing wheels to extend the internal wheel list (can be set 1+ times) |
|
'bundle' |
version of pip to install as seed: embed, bundle, none or exact version |
|
'none' |
version of setuptools to install as seed: embed, bundle, none or exact version |
|
'none' |
version of wheel to install as seed: embed, bundle, none or exact version |
|
False |
do not install pip |
|
False |
do not install setuptools |
|
False |
do not install wheel |
|
False |
disable the periodic (once every 14 days) update of the embedded wheels |
app-data ⇒ options specific to seeder app-data |
||
False |
symlink the python packages from the app-data folder (requires seed pip>=19.3) |
activators¶
core ⇒ options shared across all activators |
||
comma separated list of activators supported | activators to generate - default is all supported; choice of: |
|
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