{"id":9188,"library":"poetry-dotenv-plugin","title":"Poetry Dotenv Plugin","description":"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.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/mpeteuil/poetry-dotenv-plugin","tags":["poetry","plugin","dotenv","environment variables","configuration"],"install":[{"cmd":"poetry self add poetry-dotenv-plugin","lang":"bash","label":"Install plugin globally with Poetry"}],"dependencies":[{"reason":"Used by the plugin internally to parse and load .env files.","package":"python-dotenv","optional":false}],"imports":[{"note":"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.","wrong":"from poetry_dotenv_plugin import load_dotenv","symbol":"poetry-dotenv-plugin","correct":"This is a Poetry plugin and is not imported directly into Python code. Its functionality is activated automatically by Poetry."}],"quickstart":{"code":"# 1. Install the plugin (if not already installed)\n# poetry self add poetry-dotenv-plugin\n\n# 2. Create a .env file in your project root\n# echo 'MY_SECRET_KEY=\"supersecret\"' > .env\n# echo 'DATABASE_URL=\"postgresql://user:password@host:port/dbname\"' >> .env\n\n# 3. Create a Python script (e.g., main.py)\n# 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\n\n# 4. Run the Python script via Poetry\npoetry run python main.py","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"<=0.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The `.env` file is not located in the current working directory or a parent directory, or the plugin is not correctly installed/activated.","error":"Environment variables not set!"},{"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.","cause":"The plugin was not correctly installed using `poetry self add` or there's a conflict with your Poetry version.","error":"Poetry does not recognize 'poetry-dotenv-plugin' or 'plugin command not found'."},{"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.","cause":"Misunderstanding the plugin's default override behavior or incorrect configuration for `override_existing`.","error":"Unexpected environment variable values (e.g., system variables not overridden, or vice versa)."}]}