• Overview
  • Features
• Installation
• Usage and Configuration
  • ignore
  • location
  • Configuration via TOML file
  • Configuration via environment variables
  • Lookup hierarchy
• Examples

poetry-plugin-dotenv - is the plugin that automatically loads environment variables from a dotenv file into the environment before poetry commands are run.

• Fully type safe
• Doesn't require any dependencies
• Supports templates, interpolating variables using POSIX variable expansions
• Supports --directory - working directory for the poetry command
• Supports multiple configuration sources
• Supports configuration auto-completion and validation in IDEs such as Visual Studio Code or PyCharm (part of JSON Schema Store)

poetry self add poetry-plugin-dotenv

By default, the plugin will load the .env file from the current working directory or "higher directories".

Type: str

Default: false

Allowed values (as True): y / yes / t / on / 1 / true

Allowed values (as False): n / no / f / off / 0 / false

Prevents poetry from loading the dotenv file.

Type: str

Default: .env

If your dotenv file is located in a different path or has a different name you may set this parameter.

The plugin is able to read project-specific default values for its options from a pyproject.toml file. By default, poetry-plugin-dotenv looks for pyproject.toml containing a [tool.poetry.plugins.dotenv] section.

Example pyproject.toml:

[tool.poetry.plugins.dotenv]
ignore = "false"
location = ".env.dev"

As it was mentioned in the Features list, the schema of the plugin configuration is now part of the JSON Schema Store which brings auto-completion and validation in IDEs such as Visual Studio Code or PyCharm "out of the box".

poetry-plugin-dotenv supports the following configuration options via environment variables.

• POETRY_PLUGIN_DOTENV_LOCATION
• POETRY_PLUGIN_DOTENV_IGNORE

A pyproject.toml can override default values. Options provided by the user via environment variables override both.

# .env
DB__HOST=localhost
DB__DBNAME=local_lakehouse
DB__USER=volodymyr
DB__PASSWORD=super_secret_password
DB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}

# .env.dev
DB__HOST=dev.host
DB__DBNAME=dev_lakehouse
DB__USER=svc_team
DB__PASSWORD=super_secret_password
DB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}

# pyroject.toml
[tool.poetry.plugins.dotenv]
location = ".env.dev"

# main.py
from __future__ import annotations

import os


if __name__ == "__main__":
    try:
        print(f"Host: {os.environ['DB__HOST']!r}")
        print(f"Name: {os.environ['DB__DBNAME']!r}")
        print(f"Username: {os.environ['DB__USER']!r}")
        print(f"Password: {os.environ['DB__PASSWORD']!r}")
        print(f"Engine: {os.environ['DB__ENGINE']!r}")

    except KeyError:
        print("Environment variables not set!")

poetry run -vvv python main.py
# Loading environment variables from '.env'.
# Host: 'localhost'
# Name: 'local_lakehouse'
# Username: 'volodymyr'
# Password: 'super_secret_password'
# Engine: 'postgresql://volodymyr:super_secret_password@localhost/local_lakehouse'

# set location section in pyproject.toml
poetry run -vvv python main.py
# Loading environment variables from '.env.dev'.
# Host: 'dev.host'
# Name: 'dev_lakehouse'
# Username: 'svc_team'
# Password: 'super_secret_password'
# Engine: 'postgresql://svc_team:super_secret_password@dev.host/dev_lakehouse'

# set ignore = "true" in pyproject.toml
poetry run -vvv python main.py
# Not loading environment variables.
# Environment variables not set!

export POETRY_PLUGIN_DOTENV_LOCATION=.env.dev && poetry run -vvv python main.py
# Loading environment variables from '.env.dev'.
# Host: 'dev.host'
# Name: 'dev_lakehouse'
# Username: 'svc_team'
# Password: 'super_secret_password'
# Engine: 'postgresql://svc_team:super_secret_password@dev.host/dev_lakehouse'

export POETRY_PLUGIN_DOTENV_IGNORE=true && poetry run -vvv python main.py
# Not loading environment variables.
# Environment variables not set!