Working with Virtual Environments#
Compared to PEP 582, virtual environments are considered more mature and have better support in the Python ecosystem as well as IDEs. Therefore, virtualenv is the default mode if not configured otherwise.
Virtual environments will be used if the project interpreter (the interpreter stored in
.pdm-python, which can be checked by
pdm info) is from a virtualenv.
By default, PDM prefers to use the virtualenv layout as other package managers do. When you run
pdm install the first time on a new PDM-managed project, whose Python interpreter is not decided yet, PDM will create a virtualenv in
<project_root>/.venv, and install dependencies into it. In the interactive session of
pdm init, PDM will also ask to create a virtualenv for you.
You can choose the backend used by PDM to create a virtualenv. Currently it supports three backends:
You can change it by
pdm config venv.backend [virtualenv|venv|conda].
Create a virtualenv yourself#
You can create more than one virtualenvs with whatever Python version you want.
1 2 3 4 5 6
The location of virtualenvs#
--name is given, PDM will create the venv in
<project_root>/.venv. Otherwise, virtualenvs go to the location specified by the
They are named as
<project_name>-<path_hash>-<name_or_python_version> to avoid name collision.
You can disable the in-project virtualenv creation by
pdm config venv.in_project false. And all virtualenvs will be created under
Reuse the virtualenv you created elsewhere#
You can tell PDM to use a virtualenv you created in preceding steps, with
When no interpreter is stored in the project config or
PDM_IGNORE_SAVED_PYTHON env var is set, PDM will try to detect possible virtualenvs to use:
.venvdirectories in the project root
- The currently activated virtualenv, unless
List all virtualenvs created with this project#
1 2 3 4 5 6
Show the path or python interpreter of a virtualenv#
Remove a virtualenv#
1 2 3 4
Activate a virtualenv#
Instead of spawning a subshell like what
pdm venv doesn't create the shell for you but print the activate command to the console. In this way you won't leave the current shell. You can then feed the output to
eval to activate the virtualenv:
Additionally, if the project interpreter is a venv Python, you can omit the name argument following activate.
venv activate does not switch the Python interpreter used by the project. It only changes the shell by injecting the virtualenv paths to environment variables. For the forementioned purpose, use the
pdm use command.
For more CLI usage, see the
pdm venv documentation.
PDM doesn't provide a
shell command because many fancy shell functions may not work perfectly in a subshell, which brings a maintenance burden to support all the corner cases. However, you can still gain the ability via the following ways:
pdm run $SHELL, this will spawn a subshell with the environment variables set properly. The subshell can be quit with
- Add a shell function to activate the virtualenv, here is an example of BASH function that also works on ZSH:
1 2 3 4 5 6 7 8 9
Copy and paste this function to your
~/.bashrc file and restart your shell. Now you can run
pdm shell to activate the virtualenv.
The virtualenv can be deactivated with
deactivate command as usual.
By default when you activate a virtualenv, the prompt will show:
For example if your project is named
The format can be customized before virtualenv creation with the
venv.prompt configuration or
PDM_VENV_PROMPT environment variable (before a
pdm init or
pdm venv create).
Available variables are:
project_name: name of your project
python_version: version of Python (used by the virtualenv)
1 2 3
Run a command in a virtual environment without activating it#
1 2 3 4 5 6
There are other commands supporting
--venv flag or
PDM_IN_VENV environment variable, see the CLI reference. You should create the virtualenv with
pdm venv create --name <name> before using this feature.
Switch to a virtualenv as the project environment#
By default, if you use
pdm use and select a non-venv Python, the project will be switched to PEP 582 mode. We also allow you to switch to a named virtual environment via the
1 2 3 4
Disable virtualenv mode#
You can disable the auto-creation and auto-detection for virtualenv by
pdm config python.use_venv false.
If venv is disabled, PEP 582 mode will always be used even if the selected interpreter is from a virtualenv.
Including pip in your virtual environment#
By default PDM will not include
pip in virtual environments.
This increases isolation by ensuring that only your dependencies are installed in the virtual environment.
pip once (if for example you want to install arbitrary dependencies in CI) you can run:
1 2 3 4 5
Or you can create the virtual environment with
See the ensurepip docs for more details on
If you want to permanently configure PDM to include
pip in virtual environments you can use the