Skip to main content

No project description provided

Project description

runenv

Manage application settings with ease using runenv, a lightweight tool inspired by The Twelve-Factor App methodology for configuration through environment variables.

runenv provides:

  • A CLI for language-agnostic .env profile execution
  • A Python API for programmatic .env loading

“Store config in the environment” — 12factor.net/config

Section Status
CI/CD CI - Test
PyPI PyPI - Version Downloads
Python Python Versions
Style Black Ruff Mypy
License License - MIT
Docs CHANGELOG.md

Table of Contents


Key Features

  • 🚀 CLI-First: Use .env files across any language or platform.
  • 🐍 Python-native API: Load and transform environment settings inside Python.
  • ⚙️ Multiple Profiles: Switch easily between .env.dev, .env.prod, etc.
  • ⚙️ Multiple Formats: Use plain .env, .env.json, .env.toml, or .env.yaml
  • ⚙️ Autodetect Env File: Looking for .env, .env.json, .env.toml, and .env.yaml
  • 🧩 Framework-Friendly: Works well with Django, Flask, FastAPI, and more.

Quick Start

Installation

pip install runenv
pip install runenv[toml] # if you want to use .env.toml in python < 3.11
pip install runenv[yaml] # if you want to use .env.yaml

CLI Usage

Run any command with a specified environment:

runenv run --env-file .env.dev -- python manage.py runserver
runenv run --env-file .env.prod -- uvicorn app:app --host 0.0.0.0
runenv list [--env-file .env] # view parsed variables
runenv lint [--env-file .env] # check common errors in env file

Python API

Load .env into os.environ

Note: The load_env will not parse env_file if the runenv CLI was used, unless you force=True it.

from runenv import load_env

load_env() # loads .env
load_env(
    env_file=".env.dev",    # file to load - will be autodetected if not passed
    prefix='APP_',          # load only APP_.* variables from file
    strip_prefix=True,      # strip ^ prefix when loading variables
    force=True,             # load env_file even if the `runvenv` CLI was used
    search_parent=1,        # look for env_file in current dir and its 1 parent dirs
    require_env_file=False  # raise error if env file is missing, otherwise just ignore
)

Read .env as a dictionary

from runenv import create_env

config = create_env() # parse .env content into dictionary
config = create_env(
    env_file=".env.dev",    # file to load - will be autodetected if not passed
    prefix='APP_',          # parse only APP_.* variables from file
    strip_prefix=True,      # strip ^ prefix when parsing variables
    search_parent=1,        # look for env_file in current dir and its 1 parent dirs
)
print(config)

Options include:

  • Filtering by prefix
  • Automatic prefix stripping
  • Searching parent directories

Multiple Profiles

Use separate .env files per environment:

runenv .env.dev flask run
runenv .env.staging python main.py
runenv .env.production uvicorn app.main:app

Recommended structure:

.env.dev
.env.test
.env.staging
.env.production

Framework Integrations

Note: If you're using runenv .env [./manage.py, ...] CLI then you do not need change your code. Use these integrations only if you're using Python API.

Django

# manage.py or wsgi.py
from runenv import load_env
load_env(".env")

Flask

from flask import Flask
from runenv import load_env

load_env(".env")
app = Flask(__name__)

FastAPI

from fastapi import FastAPI
from runenv import load_env

load_env(".env")
app = FastAPI()

Sample .env File

# Basic
DEBUG=1
PORT=8000

# Nested variable
HOST=localhost
URL=http://${HOST}:${PORT}

# Quotes and comments
EMAIL="admin@example.com" # Inline comment
SECRET='s3cr3t'

Similar Tools


With runenv, you get portable, scalable, and explicit configuration management that aligns with modern deployment standards. Ideal for CLI usage, Python projects, and multi-environment pipelines.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

runenv-1.3.0.tar.gz (168.1 kB view details)

Uploaded Source

Built Distribution

runenv-1.3.0-py3-none-any.whl (12.9 kB view details)

Uploaded Python 3

File details

Details for the file runenv-1.3.0.tar.gz.

File metadata

  • Download URL: runenv-1.3.0.tar.gz
  • Upload date:
  • Size: 168.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for runenv-1.3.0.tar.gz
Algorithm Hash digest
SHA256 553265c59f5437c25e387c6adc6a91100e1770942c722285884fb901da84c6c6
MD5 ae3e04c164240d2bd2d4f85df97e03b3
BLAKE2b-256 8fee125346f632aaf4c29911d9e5947390914922884305a244a2eb77333386f5

See more details on using hashes here.

File details

Details for the file runenv-1.3.0-py3-none-any.whl.

File metadata

  • Download URL: runenv-1.3.0-py3-none-any.whl
  • Upload date:
  • Size: 12.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for runenv-1.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ad554f5a872fc45294a4933468af83b9ac6daefe4203e6482d209e4ca87aaa78
MD5 260f2d5b8a996ff8882b581158cc6763
BLAKE2b-256 f3214502466bab30ba75e434904f626d045c290d43a6f419f17b2c1e5e4b168d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page