Poetry Shell Plugin

1.0.1 · active · verified Fri Apr 17

The `poetry-plugin-shell` is an official Poetry plugin that extends the Poetry CLI with a `shell` command. This command allows users to open a subshell with their project's virtual environment automatically activated, making it easy to interact with installed project dependencies. It is currently at version 1.0.1 and generally releases updates to ensure compatibility with new Poetry versions.

Common errors

```
Command `shell` not found.
```
cause The `poetry-plugin-shell` plugin is either not installed for your Poetry CLI, or your Poetry installation is too old to support the plugin system.

fix Ensure Poetry is updated to at least 1.2.0 (`poetry self update`) and then install the plugin using `poetry self add poetry-plugin-shell`.
```
poetry.plugins.exceptions.PluginLoadError: Plugin `poetry-plugin-shell` could not be loaded because of an incompatible Poetry version.
```
cause Your Poetry CLI version is older than the required 1.2.0, which introduced the plugin system and required API.

fix Upgrade your Poetry installation to version 1.2.0 or newer using `poetry self update`.

Warnings

breaking This plugin requires Poetry version 1.2.0 or newer. Installing it with older Poetry versions will result in a plugin load error.
Fix: Upgrade your Poetry installation to a compatible version using `poetry self update` before adding the plugin.
gotcha The `poetry-plugin-shell` must be installed as a Poetry self-plugin for the Poetry CLI, not within a project's virtual environment using `pip install`.
Fix: Always use `poetry self add poetry-plugin-shell` to install the plugin. Do not try `pip install poetry-plugin-shell` in a project's virtual environment or globally.

Install

poetry self add poetry-plugin-shell Install for Poetry CLI

Quickstart

After installing the plugin using `poetry self add`, navigate to a Poetry-managed project directory and run `poetry shell`. This will open a new subshell (e.g., bash, zsh, cmd) with your project's virtual environment activated, allowing you to run project executables or Python scripts directly.

poetry shell

view raw JSON →