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

Overview

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

Features

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

Installation

poetry self add poetry-plugin-dotenv

Usage and Configuration

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

ignore

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.

location

Type: str

Default: .env

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

Configuration via TOML file

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"

[!IMPORTANT] Due to the default poetry parser, options in the plugins sections should be always strings.

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

https://github.com/pivoshenko/poetry-plugin-dotenv/assets/40499728/15d3a988-a723-49f8-960d-f91cd6bfe536

Configuration via environment variables

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

• POETRY_PLUGIN_DOTENV_LOCATION
• POETRY_PLUGIN_DOTENV_IGNORE

[!IMPORTANT] Due to the nature of environment variables, options should be always strings.

Lookup hierarchy

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

Examples

# .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!