poetry-shell

Spawn a shell within the virtual environment

$ poetry shell

poetry shell [options]

--help, -h
    Display help for the shell command.

--quiet, -q
    Do not output any message.

--verbose, -v
    Increase the verbosity of messages (e.g., -v, -vv, -vvv).

--directory, -C
    Change the current working directory to the specified path. This allows running poetry shell from outside the project root if the path points to a poetry project.

--ansi
    Force ANSI output.

--no-ansi
    Disable ANSI output.

--no-interaction, -n
    Do not ask any interactive question.

The poetry-shell command is a subcommand of the poetry tool, a modern and comprehensive dependency manager for Python projects. Its primary function is to activate a new shell instance within the context of the current project's virtual environment. This command provides a seamless way to work with project-specific dependencies without polluting the global Python environment or requiring manual activation steps.

When poetry-shell is executed, it first ensures that a virtual environment exists for the project. If one doesn't exist, poetry often prompts to create it or suggests running poetry install. Once the environment is ready, poetry-shell spawns a new shell (e.g., bash, zsh, cmd.exe) where the virtual environment is automatically activated. This means that any Python or pip commands executed within this new shell will operate on the project's isolated dependencies and Python interpreter. This isolation is crucial for reproducible builds and avoiding dependency conflicts across multiple projects.

Developers can then run development scripts, tests, or application code using the exact Python version and libraries specified in their pyproject.toml file. To exit the activated shell, simply type exit. This command significantly enhances the developer experience by ensuring a consistent and isolated workspace for each Python project managed by poetry.

• Requires poetry to be installed on the system.
• Must be executed within a poetry-managed project directory, or with the -C option pointing to one.
• If a virtual environment for the project does not exist, poetry might prompt the user to create one (e.g., by running poetry install).
• The command starts a new sub-shell. Exiting this sub-shell (e.g., with exit) returns to the parent shell.
• Does not *create* the virtual environment itself; it activates an existing or implicitly created one. For explicit creation, use poetry install.

When poetry shell is run, poetry first locates the project's pyproject.toml file to identify the virtual environment associated with it. If no virtual environment exists, poetry typically creates one automatically (or prompts the user if configured otherwise). Once the environment is located or created, poetry then executes a new shell process (e.g., bash, zsh, cmd.exe) and, crucially, configures this new shell's environment variables (like PATH) to point to the virtual environment's Python interpreter and scripts. This ensures that any subsequent Python-related commands run within this specific shell session will use the project's isolated dependencies.

To leave the activated poetry shell and return to your original shell environment, simply type exit and press Enter. This will terminate the sub-shell process that poetry shell initiated.

The poetry project was initiated by Sébastien Eustace in 2017 with the goal of providing a comprehensive and opinionated dependency manager for Python, inspired by tools like npm and yarn from the JavaScript ecosystem. It aimed to address common frustrations with pip, setuptools, and traditional virtualenv workflows, especially regarding dependency resolution and project packaging.

The poetry-shell command is an integral part of poetry's design philosophy, emphasizing isolated development environments. From its early versions, poetry integrated virtual environment management directly, and poetry-shell provided a user-friendly abstraction over manually activating these environments. This command has been a stable feature, central to poetry's promise of making Python project development more streamlined and less error-prone by ensuring developers always work within the correct dependency context.

poetry(1), venv(1), pip(1), python(1), source(1)