Managing Environments

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

Poetry always works in a virtual environment: the one that is active when you run it, or one it creates for the project. This page covers how it picks and manages that environment, for Poetry 2.5.1. The examples ran on 2026-10-22 on a machine with CPython 3.14.6, 3.13.16 and 3.12.3 installed, with Poetry’s cache and data directories pointed into a scratch directory (shown as …) and virtualenvs.in-project left at its default false, so that the environments live in the cache.

Which environment Poetry uses

  1. If Poetry runs inside an active virtual environment (or a conda environment), it uses that one and creates nothing.

  2. Otherwise it uses the environment it already created for the project, or creates one.

  3. To create one it starts from the python on PATH (with virtualenvs.use-poetry-python = true, from the Python Poetry itself was installed with). If that Python does not satisfy the project’s requires-python, Poetry looks for one that does, and otherwise asks you to choose with poetry env use.

New environments are named <project>-<hash>-py<X.Y> and created under virtualenvs.path (default {cache-dir}/virtualenvs). With virtualenvs.in-project = true (POETRY_VIRTUALENVS_IN_PROJECT), the environment is .venv inside the project instead, which many editors pick up automatically and which most examples in this section use. The setting applies when the environment is created; an existing environment in the cache keeps being used until you remove it.

With pyenv, pyenv local 3.13 before poetry install is enough: Poetry starts from the python that pyenv puts on PATH.

Source: Poetry: Managing environments, Poetry: virtualenvs.use-poetry-python.

poetry env

env use

poetry env use <python> creates (if needed) and selects the environment for an interpreter: a path, a command on PATH (python3.14), a version (3.14), or system to go back to the interpreter found on PATH without a dedicated venv.

poetry env use python3.14
poetry env use python3.13
Creating virtualenv birdtally-ziIVa4lW-py3.14 in …/envcache/virtualenvs
Using virtualenv: …/envcache/virtualenvs/birdtally-ziIVa4lW-py3.14
Creating virtualenv birdtally-ziIVa4lW-py3.13 in …/envcache/virtualenvs
Using virtualenv: …/envcache/virtualenvs/birdtally-ziIVa4lW-py3.13

Source: Poetry: Switching between environments, Poetry CLI: env use.

env list, env info and env activate

poetry env list
poetry env list --full-path
poetry env info -p
poetry env info -e
birdtally-ziIVa4lW-py3.13 (Activated)
birdtally-ziIVa4lW-py3.14
…/envcache/virtualenvs/birdtally-ziIVa4lW-py3.13 (Activated)
…/envcache/virtualenvs/birdtally-ziIVa4lW-py3.14
…/envcache/virtualenvs/birdtally-ziIVa4lW-py3.13
…/envcache/virtualenvs/birdtally-ziIVa4lW-py3.13/bin/python

(Activated) marks the environment Poetry will use, not one active in your shell. env info without options prints the environment and the base interpreter (example on Environments & Externally Managed Pythons); -p/--path prints only the path and -e/--executable only the interpreter, both handy in scripts. poetry env activate prints the command to activate it; see Basic Usage.

Source: Poetry: Listing the environments, Displaying the environment information, Activating the environment, Poetry CLI: env list, env info, env activate.

env remove

poetry env remove python3.13
poetry env remove --all
Deleted virtualenv: …/envcache/virtualenvs/birdtally-ziIVa4lW-py3.13
Deleted virtualenv: …/envcache/virtualenvs/birdtally-ziIVa4lW-py3.14

env remove accepts the same forms as env use, or the environment’s name as shown by env list.

Source: Poetry: Deleting the environments, Poetry CLI: env, env remove.

poetry python (experimental, 2.1)

poetry python manages Python interpreters themselves, downloading builds from the python-build-standalone project. The documentation labels it experimental: "This is an experimental feature, and can change behaviour in upcoming releases."

poetry python list
 Version Implementation Manager Path
 3.14.6  CPython        System  /root/.local/share/uv/python/cpython-3.14.6-linux-x86_64-gnu/bin/python3
 3.14.6  CPython        System  /root/.local/share/uv/python/cpython-3.14-linux-x86_64-gnu/bin/python3
 3.14.6  CPython        System  /root/.local/bin/python3.14
 3.13.16 CPython        System  /usr/bin/python3.13
 3.13.16 CPython        System  /usr/bin/python3
…
 3.12.3  CPython        System  /usr/bin/python3.12
…
poetry python install 3.13
poetry python list --managed
poetry python remove 3.13.11
Downloading and installing 3.13 (cpython) ... Done
Testing 3.13 (cpython) ... Done
 Version Implementation Manager Path
 3.13.11 CPython        Poetry  …/envdata/python/cpython@3.13.11/bin/python3.13
 3.13.11 CPython        Poetry  …/envdata/python/cpython@3.13.11/bin/python3
 3.13.11 CPython        Poetry  …/envdata/python/cpython@3.13.11/bin/python
Removing installation 3.13.11 (cpython) ... Done

  • install <version> takes a partial version and picks a build: here 3.13.11, which is older than the 3.13.16 the operating system had, because it is the newest 3.13 build Poetry’s download index offered. Options: -i/--implementation cpython|pypy, -t/--free-threaded, -r/--reinstall, -c/--clean (clean up if the post-install check fails). A second install 3.13 answers Python version already installed at …/cpython@3.13. Use --reinstall to install anyway ….

  • list shows every interpreter Poetry can find; -m/--managed only its own, -a/--all also downloadable versions, plus -i and -t filters.

  • remove needs the exact X.Y.Z version; poetry python remove 3.13 answers Invalid Python version requested 3.13.

  • Interpreters go to python.installation-dir ({data-dir}/python, setting added in 2.1). They are found by poetry env use like any other Python.

Source: Poetry CLI: python, python install, python list, python remove, Poetry: python.installation-dir.

Disabling environment management

poetry config virtualenvs.create false (POETRY_VIRTUALENVS_CREATE=false) makes Poetry install into whatever interpreter it runs against. The FAQ’s warning: "The recommended best practice, including when installing an application within a container, is to make use of a virtual environment", and "The Poetry team strongly encourages the use of a virtual environment." The pitfalls:

  • on a distribution Python, the PEP 668 marker blocks the install (see Environments & Externally Managed Pythons);

  • in an environment that also holds Poetry, poetry install can change Poetry’s own dependencies;

  • poetry sync should not be used there, because it would remove packages that the project does not know about.

In a container, create a venv (or let Poetry create .venv with virtualenvs.in-project = true) instead; see CI Caching & Containers.

Source: Poetry FAQ: I don’t want Poetry to manage my virtual environments.

pip and Poetry

pip never creates environments; python -m venv and pip --python <env> are its tools. The virtualenvs.* settings are listed on Configuration.

References