Registry / devops / poetry-dotenv-plugin

poetry-dotenv-plugin

cli0.2.0pypypiunverified

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.

devops

poetry self add poetry-dotenv-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · POETRY-DOTENV-PLUG

poetry-dotenv-plugin

devopspythonv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

poetry-dotenv-plugin

✓ This is a Poetry plugin and is not imported directly into Python code. Its functionality is activated automatically by Poetry.

✗ from poetry_dotenv_plugin import load_dotenv

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.

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

poetry --version

Debug

Known issues

breakingVersion 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.

affects: >=0.2.0

gotchaPoetry 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.

affects: All versions

gotchaBy 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).

affects: <=0.2.0

Errors

Common errors & fixes

Environment variables not set!

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'.

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).

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.

Upgrade

Version history

0.2.0latest on PyPI · released Jul 16, 2023

Audit

Dependencies

python-dotenvrequiredUsed by the plugin internally to parse and load .env files.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/mpeteuil/poetry-dotenv-plugin ↗

packagehttps://pypi.org/project/poetry-dotenv-plugin/ ↗