Python API

create(python, env_dir, system, prompt, bare, virtualenv_py=None)

• python should be an absolute path pointing to a Python executable. If this is not None, and does not match sys.executable, that interpreter is launched as a subprocess to run this script. Otherwise, the creation is done in-process (subprocesses may still be run in steps during the creation).

• env_dir points to the directory to create the new virtual environment.

• system specifies whether system site packages will be available for the created virtual environment.

• prompt specifies the prompt prefix used in the created virtual environment’s activate scripts.

• bare, if True, prevents any third-party libraries from being installed. This means you will not have Setuptools, pip, and Wheel available inside the created virtual environment.

• virtualenv_py should be an absolute path pointing to a virtualenv.py script. This is optional; if missing, virtualenv will not be used to create a virtual environment.

Command line API

virtenv env_dir --python PYTHON [--system] [--prompt PROMPT]

Meanings of arguments are similar to the Python API.

The python argument is required, and can be a version, such as 3.7. A suitable Python executable will be looked up automatically if possible.

When is venv used

As mentioned above, venv is always preferred if possible. virtualenv is used for the following scenarios:

• When the module venv is not available in the target Python.

• When the module ensurepip is not available in the target Python. This generally happens for Python 3.3, or distributions such as Debian that don’t like to bundle ensurepip. Without it, pip wouldn’t be available, and we don’t want that.

• When sys.real_prefix is set. This usually means the target Python is managed by a virtualenv, and venv is known to have problems working in this situation. See discussion in bpo-30811 and pypa/virtualenv#1095 for more information.