---
id: poetry-plugin-shell
version: "1.0.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# poetry-plugin-shell — Poetry plugin to run subshell with virtual environment activated

License: permissive · Maintenance: active · Downloads: 135.8K/mo

## What it is and what it does

Poetry-plugin-shell is a Poetry plugin that adds a `shell` command to launch an interactive subshell with your project's virtual environment pre-activated. It detects your current shell automatically (or falls back to the SHELL or COMSPEC environment variable) and creates the virtual environment if it doesn't exist. The plugin uses shellingham internally to identify the active shell, then spawns a new shell process with the venv activated—you exit with `exit` rather than `deactivate` to properly leave both the shell and the environment.

This plugin restores functionality that was previously built into Poetry itself. It depends on pexpect for subprocess interaction, poetry as the host framework, and shellingham for shell detection. The package supports Python 3.9 through 3.13 and is actively maintained.

Use it for:

- Quickly enter a project's virtual environment from the command line without manually sourcing activation scripts.
- Ensure a clean shell session with the correct venv activated when switching between Poetry projects.
- Automate shell setup in scripts or CI/CD workflows that need to run commands inside a Poetry project's environment.
- Detect and use the developer's preferred shell (bash, zsh, fish, etc.) automatically when activating the venv.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Poetry plugin that launches a subshell with the project's virtual environment automatically activated, replacing Poetry's built-in shell command.

Yes, if you use Poetry and want a convenient way to activate your project's virtual environment. Install friction is low, maintenance is active, and there are no known vulnerabilities. The MIT license imposes no restrictions. Install via `poetry self add poetry-plugin-shell` for the smoothest integration.

## Install

pip install poetry-plugin-shell
uv add poetry-plugin-shell
poetry add poetry-plugin-shell

## Installing poetry-plugin-shell

Before you install: Low install friction; the package is a pure Python wheel with three straightforward runtime dependencies (pexpect, poetry, shellingham). Actively maintained with a recent commit on 2026-08-10.

License in practice: MIT license is permissive; you can use this plugin freely in commercial and private projects without restriction.

Quickstart:

poetry self add poetry-plugin-shell
poetry shell

Requires Poetry to be installed; the plugin integrates as a Poetry command extension.

Verify before relying:

- Whether the plugin works with all Poetry installation methods (self, pipx inject, pip install) equally well in practice.
- Shell detection behavior on less common shells or non-standard shell configurations.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 135.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

poetry virtual environment shell, activate venv poetry plugin, poetry shell command, subshell with poetry venv, poetry environment activation, interactive shell poetry project, poetry-plugin, virtual-environment, shell-integration

[View on SkillFed](https://skillfed.io/packages/poetry-plugin-shell) · [View on PyPI](https://pypi.org/project/poetry-plugin-shell/)