https://github.com/onjin/runenv
Wrapper to run programs with different env
https://github.com/onjin/runenv
django environment-variables flask python twelve-factor
Last synced: 9 months ago
JSON representation
Wrapper to run programs with different env
- Host: GitHub
- URL: https://github.com/onjin/runenv
- Owner: onjin
- License: mit
- Created: 2015-05-31T20:54:04.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2025-06-19T04:41:24.000Z (about 1 year ago)
- Last Synced: 2025-09-29T12:27:17.409Z (9 months ago)
- Topics: django, environment-variables, flask, python, twelve-factor
- Language: Python
- Homepage: https://runenv.readthedocs.io/
- Size: 198 KB
- Stars: 4
- Watchers: 2
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Authors: AUTHORS.md
Awesome Lists containing this project
README
# runenv
Manage application settings with ease using `runenv`, a lightweight tool inspired by [The Twelve-Factor App](https://12factor.net/config) 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](https://12factor.net/config)
| Section | Status |
|----------|--------|
| CI/CD | [](https://github.com/onjin/runenv/actions/workflows/test.yml) |
| PyPI | [](https://pypi.org/project/runenv/) [](https://pypi.org/project/runenv/) |
| Python | [](https://pypi.org/project/runenv/) |
| Style | [](https://github.com/psf/black) [](https://github.com/astral-sh/ruff) [](https://github.com/python/mypy) |
| License | [](https://spdx.org/licenses/) |
| Docs | [CHANGELOG.md](CHANGELOG.md) |
---
## Table of Contents
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [CLI Usage](#cli-usage)
- [Python API](#python-api)
- [Multiple Profiles](#multiple-profiles)
- [Framework Integrations](#framework-integrations)
- [Sample `.env` File](#sample-env-file)
- [Similar Tools](#similar-tools)
---
## 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
```bash
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:
```bash
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.
```python
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
```python
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:
```bash
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
```python
# manage.py or wsgi.py
from runenv import load_env
load_env(".env")
```
### Flask
```python
from flask import Flask
from runenv import load_env
load_env(".env")
app = Flask(__name__)
```
### FastAPI
```python
from fastapi import FastAPI
from runenv import load_env
load_env(".env")
app = FastAPI()
```
---
## Sample `.env` File
```ini
# 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
- [python-dotenv](https://github.com/theskumar/python-dotenv) – Python-focused, lacks CLI tool
- [envdir](https://github.com/jezdez/envdir) – Directory-based env manager
- [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) – Linter for `.env` files
---
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.