poetry-env

Print the command to activate a virtualenv

$ poetry env activate

$ poetry env info [[-p|--path]] [[-e|--executable]]

$ poetry env list --full-path

$ poetry env remove python [path/to/executable|environment_name] | poetry env remove --all

$ poetry env use python [path/to/executable]

poetry env <subcommand> [<options>] [<arguments>]

use <python>
    Activates a specific Python version (e.g., `python3.9`, `3.8.10`, or a full path to an executable) to create or switch to a virtual environment for the current project. If a virtual environment for the specified Python version does not exist, Poetry will attempt to locate the interpreter and create one.

info
    Displays detailed information about the currently active virtual environment for the project, including its absolute path, Python version, associated project root, and the number of installed packages.

list
    Lists all virtual environments that Poetry recognizes as being associated with the current project or, if run outside a project, all globally managed environments.
Options:
    --full-path: Displays the absolute path for each listed virtual environment.

remove [<python> | <path> | --all]
    Removes one or more virtual environments. You can specify a Python version (e.g., `3.8`), a direct path to an environment, or use the --all flag to remove all virtual environments associated with the current project.

path
    Prints the absolute path to the root directory of the currently active virtual environment. This is useful for scripting or for manually navigating to the environment's directory.

python
    Prints the absolute path to the Python executable within the currently active virtual environment. This can be used to directly invoke the environment's Python interpreter.

The poetry env command is a fundamental subcommand within the Poetry ecosystem, designed for comprehensive management of isolated Python virtual environments. It empowers developers to seamlessly create, activate, inspect, and remove virtual environments that are tightly coupled with their specific projects.

By abstracting the complexities of underlying tools like virtualenv or venv, poetry env streamlines the process of ensuring project dependencies are isolated and consistent, thereby preventing conflicts across different projects. It integrates directly with a project's pyproject.toml file, automatically linking environments and facilitating automatic environment creation when commands like poetry install or poetry run are executed.

This command is crucial for maintaining a clean, reproducible, and efficient development workflow, allowing developers to switch between Python versions and dependency sets with ease, ensuring each project operates in its own dedicated space.

• Poetry Installation: poetry env relies entirely on a functional Poetry installation.
• PATH Dependency: When using poetry env use, Poetry relies on the system's PATH to locate specified Python interpreters. Ensure your desired Python versions are discoverable.
• Environment Location: By default, Poetry stores virtual environments in a centralized cache (usually `~/.cache/pypoetry/virtualenvs/`), which might be unexpected if you are used to project-local environments. This can be configured.
• No Direct Shell Activation: poetry env does not directly activate a shell within the environment; use `poetry shell` for that purpose.

By default, Poetry stores virtual environments in a centralized global cache, typically located at ~/.cache/pypoetry/virtualenvs/. Each environment's directory name is usually derived from the project's name and a unique hash. This default location can be customized globally using `poetry config virtualenvs.path ` or configured to create environments directly within the project directory using `poetry config virtualenvs.in-project true`.

One of the key benefits of Poetry's environment management is its automation. When you execute essential commands like poetry install, poetry add, or poetry run for a project, Poetry automatically checks for an associated virtual environment. If no environment is found or if the specified Python version is not active, it will automatically create and configure a new one based on the Python version requirements defined in your project's pyproject.toml, or use an available system Python if no specific version is indicated.

Virtual environments managed by poetry env are deeply integrated with the project's pyproject.toml file. Poetry leverages this file not only for dependency resolution but also to determine the target Python version for the environment. This tight linkage ensures that the created environment is precisely tailored for the project's needs, promoting consistency and simplifying dependency management throughout the development lifecycle.

Poetry, created by Sébastien Eustace, emerged as a modern, opinionated Python dependency manager and package builder, aiming to provide a more holistic workflow than fragmented tools like `pip` with `setuptools` and `virtualenv`. The poetry env subcommand has been a foundational component since Poetry's early development, addressing the common pain point of virtual environment management. Its integration reflects Poetry's core philosophy of offering a complete, self-contained solution for Python project development, ensuring environments are seamlessly linked to projects and their `pyproject.toml` configurations.

poetry(1), pip(1), python(1), venv(1), virtualenv(1), pyenv(1), conda(1)