Poetry Plugin Dotenv

3.3.0 verified Fri May 01 auth: no python

Automatically loads environment variables from .env files before running Poetry commands. Currently at version 3.3.0, with active development and monthly releases.

pip install poetry-plugin-dotenv

Common errors

error ModuleNotFoundError: No module named 'poetry.plugins' ↓

cause The plugin is not installed in the same environment as Poetry, or Poetry version is too old.

fix

Install the plugin in Poetry's environment: 'pipx inject poetry poetry-plugin-dotenv' or 'pip install poetry-plugin-dotenv' in the same virtualenv.

error Error: The Poetry Plugin Dotenv is not configured properly. Please check your installation. ↓

cause The plugin's configuration was not enabled or there is a version mismatch with Poetry.

fix

Run 'poetry self add poetry-plugin-dotenv' or 'pipx inject poetry poetry-plugin-dotenv' and then 'poetry config plugins.poetry-plugin-dotenv.enabled true'.

Warnings

gotcha The plugin does not load .env files for 'poetry shell' by default; you must set the environment variable POETRY_DOTENV_SHELL=1 to enable that. ↓

fix export POETRY_DOTENV_SHELL=1 before using 'poetry shell'

gotcha By default, the plugin loads only one .env file. If you have multiple dotenv files (e.g., .env.development), you must set the POETRY_DOTENV_PATH environment variable. ↓

fix export POETRY_DOTENV_PATH=.env.development or use the --dotenv-path option if available

gotcha Poetry 2.0 changed plugin loading. The plugin must be installed in the same Python environment as Poetry. If you use pipx, install it with: pipx inject poetry poetry-plugin-dotenv ↓

fix pipx inject poetry poetry-plugin-dotenv

Imports

PoetryPluginDotenv

wrong

from poetry_plugin_dotenv import PoetryPluginDotenv

correct

from poetry_plugin_dotenv.plugin import PoetryPluginDotenv

The plugin class is in the plugin submodule, not the package root.

DotenvPlugin

wrong

from poetry_plugin_dotenv import DotenvPlugin

correct

from poetry_plugin_dotenv.plugin import DotenvPlugin

Older alias; direct import from package root fails.

Quickstart

Install the plugin, enable it, create a .env file, and run a poetry command to see the variable loaded.

pip install poetry-plugin-dotenv
poetry config plugins.poetry-plugin-dotenv.enabled true
# Create .env file with your variables
# Then run any poetry command - they will be loaded automatically
echo "MY_VAR=hello" > .env
poetry run python -c "import os; print(os.environ.get('MY_VAR', 'not set'))"