VIRTUALENV(1)

NAME
virtualenv - Python virtual environment creator

SYNOPSIS
virtualenv [--version] [--with-traceback] [-v | -q] [--app-data APP_DATA] [--clear-app-data] [--discovery {builtin}] [-p py] [--creator {builtin,cpython3-posix,venv}] [--seeder {app-data,pip}] [--no-seed]

    [--activators comma_sep_list] [--clear] [--system-site-packages] [--symlinks | --copies] [--download | --no-download] [--extra-search-dir d [d ...]] [--appdirs version] [--distlib version] [--colorama version] [--pyparsing version] [--contextlib2 version] [--chardet version] [--requests version] [--certifi version] [--pkg_resources version] [--progress version] [--pip version] [--distro version] [--html5lib version] [--msgpack version] [--six version] [--retrying version] [--lockfile version] [--packaging version] [--pep517 version] [--CacheControl version] [--setuptools version] [--webencodings version] [--urllib3 version] [--wheel version] [--pytoml version] [--idna version] [--no-pip] [--no-setuptools] [--no-wheel] [-h] dest

DESCRIPTION

The virtualenv utility creates virtual Python instances, each invokable with its own Python executable. Each instance can have different sets of modules, installable via easy_install. Virtual Python instances can also be created without root access.

  optional arguments:

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

--with-traceback
    on failure also display the stacktrace internals of virtualenv (default: False)

--app-data APP_DATA
    a data folder used as cache by the virtualenv (default: <temp folder>)

--clear-app-data
    start with empty app data folder (default: False)

-h, --help
    show this help message and exit

  verbosity:

    verbosity = verbose - quiet, default INFO, mapping => CRITICAL=0, ERROR=1, WARNING=2, INFO=3, DEBUG=4, NOTSET=5

-v, --verbose
    increase verbosity (default: 2)

-q, --quiet
    decrease verbosity (default: 0)

  discovery:

    discover and provide a target interpreter

--discovery {builtin}
    interpreter discovery method (default: builtin)

-p py, --python py
    target interpreter for which to create a virtual (either absolute path or identifier string) (default: /usr/bin/python3)

  creator:

    options for creator builtin

--creator {builtin,cpython3-posix,venv}
    create environment via (builtin = cpython3-posix) (default: builtin)

dest
    directory to create virtualenv at

--clear
    remove the destination directory if exist before starting (will overwrite files otherwise) (default: False)

--system-site-packages
    give the virtual environment access to the system site-packages dir (default: False)

--symlinks
    try to use symlinks rather than copies, when symlinks are not the default for the platform (default: True)

--copies, --always-copy
    try to use copies rather than symlinks, even when symlinks are the default for the platform (default: False)

  seeder:

    options for seeder app-data

--seeder {app-data,pip}
    seed packages install method (default: app-data)

--no-seed, --without-pip
    do not install seed packages (default: False)

--download
    pass to enable download of the latest appdirs, distlib, colorama, pyparsing, contextlib2, chardet, requests, certifi, pkg_resources, progress, pip, distro, html5lib, msgpack, six, retrying, lockfile, packaging, pep517, CacheControl, setuptools, webencodings, urllib3, wheel, pytoml, and idna from PyPI (default: False)

--no-download, --never-download
    pass to disable download of the latest appdirs, distlib, colorama, pyparsing, contextlib2, chardet, requests, certifi, pkg_resources, progress, pip, distro, html5lib, msgpack, six, retrying, lockfile, packaging, pep517, CacheControl, setuptools, webencodings, urllib3, wheel, pytoml, and idna from PyPI (default: True)

--extra-search-dir d [d ...]
    a path containing wheels the seeder may also use beside bundled (can be set 1+ times) (default: [])

--appdirs version
    appdirs version to install, bundle for bundled (default: latest)

--distlib version
    distlib version to install, bundle for bundled (default: latest)

--colorama version
    colorama version to install, bundle for bundled (default: latest)

--pyparsing version
    pyparsing version to install, bundle for bundled (default: latest)

--contextlib2 version
    contextlib2 version to install, bundle for bundled (default: latest)

--chardet version
    chardet version to install, bundle for bundled (default: latest)

--requests version
    requests version to install, bundle for bundled (default: latest)

--certifi version
    certifi version to install, bundle for bundled (default: latest)

--pkg_resources version
    pkg_resources version to install, bundle for bundled (default: latest)

--progress version
    progress version to install, bundle for bundled (default: latest)

--pip version
    pip version to install, bundle for bundled (default: latest)

--distro version
    distro version to install, bundle for bundled (default: latest)

--html5lib version
    html5lib version to install, bundle for bundled (default: latest)

--msgpack version
    msgpack version to install, bundle for bundled (default: latest)

--six version
    six version to install, bundle for bundled (default: latest)

--retrying version
    retrying version to install, bundle for bundled (default: latest)

--lockfile version
    lockfile version to install, bundle for bundled (default: latest)

--packaging version
    packaging version to install, bundle for bundled (default: latest)

--pep517 version
    pep517 version to install, bundle for bundled (default: latest)

--CacheControl version
    CacheControl version to install, bundle for bundled (default: latest)

--setuptools version
    setuptools version to install, bundle for bundled (default: latest)

--webencodings version
    webencodings version to install, bundle for bundled (default: latest)

--urllib3 version
    urllib3 version to install, bundle for bundled (default: latest)

--wheel version
    wheel version to install, bundle for bundled (default: latest)

--pytoml version
    pytoml version to install, bundle for bundled (default: latest)

--idna version
    idna version to install, bundle for bundled (default: latest)

--no-pip
    do not install pip (default: False)

    Because Debian uses wheels built from system packages rather than pip's bundled wheels, Debian also includes those system wheels in the base virtualenv. The --no-pip option will also cause the additional wheels to not be included.

--no-setuptools
    do not install setuptools (default: False)

--no-wheel
    do not install wheel (default: False)

    Because wheel is one of the required wheels for pip (see above), --no-wheel has no effect unless --no-pip is also used.

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

  activators:

    options for activation scripts

--activators comma_sep_list
    activators to generate - default is all supported (default: bash,cshell,fish,powershell,python,xonsh)

--prompt prompt
    provides an alternative prompt prefix for this environment (default: None)

config file $HOME/.config/virtualenv/virtualenv.ini (change via env var VIRTUALENV_CONFIG_FILE)

NOTES

python2 virtualenvs
    To run pip with python2 requires ipaddr, which is no longer available in the Debian archive (which is why it is not included in the package). Additional steps are required:

    [sudo] apt install python3-pip python3-virtualenv
    pip3 install ipaddr
    [sudo] cp $WHEEL_LOCATION/ipaddr-2.2.0-py2.py3-none-any.whl /usr/share/python-wheels/
    [sudo] apt install python2.7

    When ipaddr is installed via pip3, pip3 will list the installation location.  Copy the ipaddr wheel into /usr/share/python-wheels and then create your virtualenv.

    The example uses the python2.7 package from the Debian archive. Eventually that will be removed and users will have to build their own interpreter.

AUTHORS

This man-page was created using help2man and then updated by Scott Kitterman <scott@kitterman.com> and is licensed under the same terms as virtualenv.