Poetry Dotenv Plugin

0.2.0 · active · verified Thu Apr 16

A Poetry plugin that automatically loads environment variables from `.env` files into the environment before Poetry commands are run. It is currently at version 0.2.0 and provides an essential feature for managing project-specific configurations by integrating seamlessly with Poetry's workflow.

Common errors

```
Environment variables not set!
```
cause The `.env` file is not located in the current working directory or a parent directory, or the plugin is not correctly installed/activated.

fix Ensure the `.env` file is in the project root or specify its path using `POETRY_DOTENV_LOCATION` environment variable or `[tool.dotenv].location` in `pyproject.toml`. Verify the plugin is installed globally with `poetry self show plugins`.
```
Poetry does not recognize 'poetry-dotenv-plugin' or 'plugin command not found'.
```
cause The plugin was not correctly installed using `poetry self add` or there's a conflict with your Poetry version.

fix Reinstall the plugin using `poetry self add poetry-dotenv-plugin`. Ensure your Poetry version meets the plugin's requirements (typically Poetry 1.2+ for plugins). Check `poetry self show plugins` to confirm activation.
```
Unexpected environment variable values (e.g., system variables not overridden, or vice versa).
```
cause Misunderstanding the plugin's default override behavior or incorrect configuration for `override_existing`.

fix Review the plugin's default behavior regarding environment variable overriding. If on version 0.2.0+, use `[tool.dotenv].override_existing = false` in `pyproject.toml` or `POETRY_DOTENV_OVERRIDE_EXISTING=false` to prevent overriding existing system variables.

Warnings

breaking Version 0.2.0 changed how development dependencies are managed in `pyproject.toml`, switching from the deprecated `[tool.poetry.dev-dependencies]` section to Poetry's new `[tool.poetry.group.dev.dependencies]` groups.
Fix: Update your `pyproject.toml` to use `[tool.poetry.group.dev.dependencies]` for development dependencies, aligning with modern Poetry practices. Refer to Poetry's official documentation on dependency groups.
gotcha Poetry plugins are installed globally for your Poetry installation, not on a per-project basis. This means `poetry-dotenv-plugin` will attempt to load `.env` files for *any* Poetry project you work on, which might lead to unexpected variable loading if `.env` files exist in unrelated projects.
Fix: Be mindful of where you place `.env` files. For projects where `.env` loading is undesirable, consider using the plugin's configuration options (e.g., `POETRY_DONT_LOAD_DOTENV` environment variable or `[tool.dotenv].ignore` in `pyproject.toml`) to disable it for specific projects.
gotcha By default, the plugin will override existing environment variables with those found in the `.env` file. The 0.2.0 release added an option to prevent this, but the default behavior remains to override unless configured otherwise.
Fix: If you need to preserve existing environment variables, ensure you are on version 0.2.0 or newer and configure the plugin to not override them. Consult the plugin's documentation for the specific configuration option (e.g., `[tool.dotenv].override_existing = false` in `pyproject.toml` or `POETRY_DOTENV_OVERRIDE_EXISTING=false` env var).

Install

poetry self add poetry-dotenv-plugin Install plugin globally with Poetry

Imports

poetry-dotenv-plugin
wrong:
```
from poetry_dotenv_plugin import load_dotenv
```
correct:
```
This is a Poetry plugin and is not imported directly into Python code. Its functionality is activated automatically by Poetry.
```
The plugin automatically injects variables into the environment for `poetry run` and `poetry shell` commands. Do not attempt to import it in your Python code like a regular library.

Quickstart

This quickstart demonstrates how to install the `poetry-dotenv-plugin`, define environment variables in a `.env` file, and then access them within a Python script executed using `poetry run`. The plugin automatically loads the variables without explicit code changes.

# 1. Install the plugin (if not already installed)
# poetry self add poetry-dotenv-plugin

# 2. Create a .env file in your project root
# echo 'MY_SECRET_KEY="supersecret"' > .env
# echo 'DATABASE_URL="postgresql://user:password@host:port/dbname"' >> .env

# 3. Create a Python script (e.g., main.py)
# print('import os\n\nif __name__ == "__main__":\n    print(f"My secret key: {os.environ.get(\'MY_SECRET_KEY\', \'NOT_SET\')}")\n    print(f"Database URL: {os.environ.get(\'DATABASE_URL\', \'NOT_SET\')}")') > main.py

# 4. Run the Python script via Poetry
poetry run python main.py

view raw JSON →