An opinionated but flexible Python virtual environment tool.
Enables straightforward creation, removal, or replacement of Python virtual environments using venv, pyenv-virtualenv, or conda, using predictable names/locations and flexible strategies.
Intended to be used by either developers or consumers of source-available Python packages.
Warning
python-venv is deprecated and no longer maintained. Please use uv instead.
- Recent Changes
- Requirements
- Installation
- Invocation
- Quick Start
- Types of Virtual Environments
- Installing Requirements
- Python Interpreter
- Command-line Autocompletion
- Backwards-Incompatible Changes
- References
See NEWS.
For incompatible changes beginning in v0.7.0, see Backwards-Incompatible Changes.
- A Python interpreter, version 3.7 or later
- The Python packages listed in requirements.txt
The recommended method of installing python-venv is to install it into a virtual environment. Currently installation from a wheelfile or from source is supported. Installing from a wheelfile is recommended.
python-venv can create the virtual environment and install itself for you. For a venv environment:
python3 -m python_venv create -t venv -r wheel --dry-run
python-venv will say what it would do. To actually do it, remove the
--dry-run argument:
python3 -m python_venv create -t venv -r wheel
Similarly, for a pyenv-virtualenv environment:
python3 -m python_venv create -t pyenv -r wheel --dry-run
python3 -m python_venv create -t pyenv -r wheel
Or, for a conda environment:
python3 -m python_venv create -t conda -r wheel --dry-run
python3 -m python_venv create -t conda -r wheel
python-venv may be invoked in a few different ways:
-
Before installation, using the executable script in the top of the source directory:
./python-venv -
After installation into a Python virtual environment and activation of that environment, using the executable script:
python-venv -
Using the Python interpreter, either from the source directory or from an activated virtual enviroment where python-venv has been installed:
python3 -m python_venv
Some of the above methods may differ for some command-line interpreters on Windows.
For the remainder of this document, we will use python-venv to mean any of
the above methods.
Create a Python virtual environment using venv at .venv for the Python
source project in the current directory, using requirements.txt as the list
of requirements:
python-venv create -t venv -r plain
Remove that virtual enviroment:
python-venv remove -t venv
Create a conda virtual environment named after the Python source project
in the current directory using requirements.txt:
python-venv create -t conda -r plain
Remove that conda environment:
python-venv remove -t conda -r plain
Create a pyenv-virtualenv environment for development, named after the
Python source project in the current directory, and using
requirements_dev.txt:
python-venv create -t pyenv -r dev
Replace it with a new environment after updating requirements_dev.txt:
python-venv replace -t pyenv -r dev
Display command-line help:
python-venv --help
python-venv knows how to create virtual environments using:
- The venv module built into Python 3.
- The pyenv-virtualenv plugin for pyenv.
- The conda tool that accompanies a Miniconda or Anaconda Python distribution.
Use the -t or --env-type option to say what type of virtual environment to
create or remove.
📌 NOTE:
Python-venv can create "anonymous"
venvenvironments in a predictably named folder under the current directory, ornamed-venvenvironments in a dedicated directory and named after the Python source project in the current directory. See Names and Some Flexibility for more about this.
python-venv understands several different opinionated ways of specifying what to install into a virtual environment ("requirement schemes"):
- Plain -- using a
requirements.txtfile. - Frozen -- using frozen requirements (from
pip freeze) in arequirements_frozen.txtfile. - Package -- using the name of the Python source project in the current
directory as a package to
pip install. - Pip -- using the additional arguments on the command line as arguments
to
pip install. - Source -- using the Python source project in the current directory as a
thing to build via
python3 -m build --sdistand then installing the resulting source distrbution usingpip. - Wheel -- using the Python source project in the current directory as a
thing to build via
python3 -m buildand then installing the resulting wheelfile usingpip. - Dev -- using a
requirements_dev.txtfile. - Devplus -- using a combination of requirements files to install packages as a development environment for the Python source project in the current directory.
These schemes correspond roughly to the following:
| Kind of Requirements | Corresponding Install Command |
|---|---|
| plain | pip install -r requirements.txt |
| frozen | pip install -r requirements_frozen.txt |
| package | pip install this-package-name |
| pip | pip install ARG1 ARG2 ... |
| source | python3 -m build --sdist && pip install SDIST |
| wheel | python3 -m build && pip install WHEELFILE |
| dev | pip install -r requirements_dev.txt |
| devplus | pip install -r requirements.txt -r dev/requirements_build.txt -r dev/requirements_dev.txt -r dev/requirements_test.txt |
📌 NOTE: Prior to v0.7.0, the
devplusrequirement scheme was known asdev, and there was no genericdevequivalent.
📌 NOTE: Prior to v0.7.0, the
-Pcommand-line argument meant--package. Now it means--pip.
⭐ HINT: When using
--pip, to keep python-venv from misinterpreting pip requirements as options, Use plain dashes (--) as the first additional argument on the command line. For example:python-venv create -t venv -r pip -e .venv -- -r my-requirements.txt
python-venv creates devplus environments from the following requirements
files that correspond to arguments of the setup() call in setup.py:
| Requirements | setup() argument |
Purpose |
|---|---|---|
| requirements.txt | install_requires |
Runtime requirements |
| dev/requirements_dev.txt | setup_requires |
Requirements for developing |
| dev/requirements_test.txt | tests_require |
Requirements for running tests |
| dev/requirements_build.txt | None | Requirements for building packages |
This is the scheme followed by python-venv's setup.py. It's quite
likely it may not work well for everyone.
Python-venv's main purpose in life is to create or re-create Python environments in a predictable way using a single command. It uses one of two approaches or naming schemes:
- Anonymous environments with a predictable name in the current directory.
- Named environments in a dedicated directory and named using a basename.
Which naming scheme python-venv uses depends on the environment type:
| Environment Type | Naming Scheme | Example |
|---|---|---|
| venv | anonymous | ./.venv |
| named-venv | named | ~/.venvs/python-venv |
| conda | named | <CONDA_PREFIX>/envs/python-venv |
| pyenv | named | <PYENV_ROOT>/<VERSION>/envs/python-venv |
In the named environment examples above, python-venv is the basename. The
default basename comes from the Python source project in the current directory
(python3 setup.py --name), with underscores replaced by hyphens (for this
Python project, that works out to python-venv).
The basename is used for:
- The name of non-
devnamed environments as-is. - The name of
devanddevplusnamed environments, with a-devsuffix added (python-venv-dev). - The name of the Python package to install for
packageenvironments.
You can choose your own basename using the --basename option; this will
keep python-venv from trying to use setup.py to find the name:
python-venv create -t named-venv -r dev --basename python-venv-0.1.0
python-venv create -t pyenv -r plain --basename requirements-test
python-venv create -t venv -r package --basename mypackage
You can also choose your own environment name using the --env-name option if
you want a different environment name:
python-venv create -t conda -r plain --env-name myenv
python-venv create -t pyenv -r dev --env-name myenv-development
python-venv create -t named-venv -r devplus --venvs-dir ~/.venvs-dev --env-name myenv
Or, if you are using venv environments, if you want your virtual environment
somewhere besides .venv:
python-venv create -t venv -r plain --env-name .python-env
python-venv create -t venv -r plain --env-name /path/to/myenv
If the place you're running python-venv from is not the spot where the
Python source project is that you want to act on, you can tell python-venv
to change directories before doing anything using the -C/--cd option:
python-venv create -t venv -r plain --cd /some/other/dir
Typical Python setups, with a "system" Python and possibly either an Anaconda/Miniconda or a pyenv install, will generally work well with python-venv, whether you're creating stock venv environments or something more esoteric. But there are times when you may need more control over:
- What Python interpreter you use to create venv environments.
- What the name of the Python interpreter is inside your virtual environment.
- What Python interpreter version to place into your conda environment.
python-venv tries to help with that.
Use the --python option to tell python-venv to use a specific Python
interpreter. The default is python3.
You may supply either a base command name, like python3, or a full path,
like /usr/bin/python3.
If you supply a base command name:
- The command is looked for on the PATH, and the first matching command is
used for Python commands that create virtual environments (such as
python3 -m venv ...). - The base command name is also used to refer to the Python interpreter
inside the virtual environment, for running Python commands after the
virtual environment has been created (such as
/path/to/your/env/bin/python3 -m pip install ...).
If you supply a full path:
- The path is used as-is for Python commands that create virtual environments.
For example,
/usr/local/bin/mypython -m venv .... - The base command name from the full path is used to refer to the Python
interpreter inside the virtual environment. For example,
/path/to/your/env/bin/mypython -m pip install ....
You may choose a different default value for --python by setting the
PYTHON_VENV_USE_PYTHON environment variable. For example, with the Bash
shell:
export PYTHON_VENV_USE_PYTHON=/usr/local/bin/mypython
conda create allows (in fact, requires) you to specify a Python version when
creating a conda environment. The default is python=3, selecting the
latest Python 3 version available. If you want more control over that, use
the --python-version option and specify a conda-compatible version. For
example:
python-venv create --conda --python-version 3.8 ...
pyenv also allows choosing a Python version to run. When creating a pyenv
environment, you can use the --python-version option to choose one of the
versions listed by pyenv versions. Examples:
python-venv create --pyenv --python-version 3.9.7 ...
python-venv create --pyenv --python-version system ...
This option only works with the create and replace subcommands (a Python
interpreter is not invoked when removing environments), and only for conda
and pyenv environments.
⭐ HINT: Use the
--pythonoption if you need to select a specific Python version forvenvenvironments.
You may choose a default value for for --python-version by setting the
PYTHON_VENV_USE_PYTHON_VERSION environment variable. For example, with the
Bash shell:
export PYTHON_VENV_USE_PYTHON_VERSION=3.9.7
python-venv provides command-line autocompletion for the Bash command-line shell and compatible shells, using the argcomplete Python package.
For instructions on how to enable completion:
python-venv completion
As of v0.7.0, there are a few significant changes to command-line flags:
| Old (pre-0.7.0) | New (post-0.7.0) | Description |
|---|---|---|
-d, --dev, -r dev |
-D, --devplus, -r devplus |
Opinionated dev requirements |
| nothing | -d, --dev, -r dev |
Generic requirements_dev.txt |
-P, --package, -r package |
--package, -r package |
Install a package named like the current Python project |
| nothing | -P, --pip, -r pip |
Install packages/wheels/pip requirements named on the command line |