Important

Due to personal reasons, the project was not able to be updated further, so we decided that it would be impossible to update it further. We announce today that the maintenance will be completed on August 30, 2025 as of KST.

The docs site will be hosted until March-April of next year upon expiration of the domain. Thank you for using it.

SimpleEnvs

Ultra-secure, high-performance .env file loader for Python
Drop-in replacement for python-dotenv with enterprise security and 2-40x performance

🚀 Why SimpleEnvs?

• 🏃‍♂️ 2-40x faster than python-dotenv (verified benchmarks)
• 🔒 Enterprise-grade security with memory isolation
• 🎯 Automatic type conversion (int, bool, float)
• ⚡ Zero configuration - works out of the box
• 🔄 100% python-dotenv compatible API
• 🔍 Smart directory scanning - finds .env files automatically

📦 Installation

pip install simpleenvs-python

⚡ Quick Start

Python-dotenv Migration (1-line change!)

# Before (python-dotenv)
from dotenv import load_dotenv
load_dotenv()

# After (SimpleEnvs) - Only change the import!
from simpleenvs import load_dotenv
load_dotenv()  # Same API, up to 40x faster! 🚀

Basic Usage

# Create .env file
echo "APP_NAME=MyApp\nDEBUG=true\nPORT=8080" > .env

# Load environment variables
from simpleenvs import load_dotenv
load_dotenv()

# Access variables
import os
print(os.getenv('APP_NAME'))  # "MyApp"
print(os.getenv('DEBUG'))     # "True" (auto-converted!)
print(os.getenv('PORT'))      # "8080"

Type-Safe Access

import simpleenvs

simpleenvs.load_dotenv()

# Type-safe getters
app_name = simpleenvs.get_str('APP_NAME', 'DefaultApp')  # str
debug = simpleenvs.get_bool('DEBUG', False)             # bool  
port = simpleenvs.get_int('PORT', 8080)                 # int

📊 Performance

Latest GitHub Actions benchmark results:

Variables	File Size	python-dotenv	SimpleEnvs Standard	SimpleEnvs Secure	Speedup
10 vars	482B	2.0ms	0.1ms	0.4ms	13.5x faster ⚡
50 vars	1.3KB	5.9ms	0.2ms	0.5ms	23.8x faster ⚡
100 vars	2.4KB	10.9ms	0.4ms	0.6ms	28.3x faster ⚡
500 vars	11KB	51.3ms	2.0ms	1.7ms	26.1x faster ⚡
1000 vars	22KB	105.1ms	5.0ms	2.7ms	20.9x faster ⚡
5000 vars	111KB	633.3ms	72.5ms	12.5ms	8.7x faster 🚀

Key discovery: Secure mode (with enterprise security) can be faster than standard mode on larger files!

Test yourself:

# Run the same benchmark as our CI
python -m simpleenvs.benchmark --quick

# Include secure mode testing
python -m simpleenvs.benchmark --secure

🔒 Security Features

Simple Mode (Default)

Perfect for development and most production use cases:

from simpleenvs import load_dotenv
load_dotenv()  # Variables stored in os.environ

Secure Mode (Enterprise)

Memory-isolated environment variables that never touch os.environ:

from simpleenvs import load_dotenv_secure, get_secure

load_dotenv_secure()  # Memory-isolated loading

# Secure access (not in os.environ!)
jwt_secret = get_secure('JWT_SECRET')
db_password = get_secure('DB_PASSWORD')

# Verify isolation
import os
print(os.getenv('JWT_SECRET'))  # None - properly isolated! 🔒

🛡️ Security Test Matrix

Attack Vector	Tests	Status	Protection Level
Path Traversal	8/8 ✅	../../../etc/passwd	🔴 BLOCKED
Script Injection	7/7 ✅	<script>alert('xss')	🔴 BLOCKED
Command Injection	7/7 ✅	$(rm -rf /)	🔴 BLOCKED
File Size Attacks	4/4 ✅	15MB+ malicious files	🔴 BLOCKED
Memory Security	3/3 ✅	Isolation verification	🟢 SECURED
Type Safety	5/5 ✅	Invalid conversions	🟡 HANDLED
Edge Cases	17/17 ✅	Unicode, encoding, etc.	🟢 ROBUST

Security Testing

# Run comprehensive security tests
python -m simpleenvs.vuln_test

# Sample threats automatically blocked:
# ❌ ../../../etc/passwd           # Path traversal
# ❌ <script>alert('xss')</script> # Script injection  
# ❌ $(rm -rf /)                   # Command injection
# ❌ 15MB+ malicious files         # DoS attacks
# ✅ Memory isolation verified     # Enterprise security
# 📊 Total: 51/51 tests passed (100% success rate)

🔍 Smart Directory Scanning

Unlike python-dotenv, SimpleEnvs automatically finds your .env files:

# Your project structure
my-project/
├── app.py                    # Run from here
├── config/
│   └── .env                 # ✅ Found automatically!
├── environments/
│   └── .env.production      # ✅ Found automatically!
└── docker/
    └── .env.docker          # ✅ Found automatically!

# SimpleEnvs (auto-discovery)
from simpleenvs import load_dotenv
load_dotenv()  # Finds the first .env file automatically!

# Manual control when needed
load_dotenv('.env.production')         # Specific file
load_dotenv('config/database.env')     # Custom path
simpleenvs.load(max_depth=3)          # Search deeper

🎯 Advanced Features

Async Support

import simpleenvs

# Async loading
await simpleenvs.load('.env')
await simpleenvs.load_secure('.env')

# Or one-liner
from simpleenvs import aload_dotenv
await aload_dotenv()

FastAPI Integration

from fastapi import FastAPI
import simpleenvs

app = FastAPI()

@app.on_event("startup")
async def startup():
    # Public config
    await simpleenvs.load('config.env')
    
    # Sensitive secrets (memory-isolated)
    await simpleenvs.load_secure('secrets.env')

@app.get("/config")
def get_config():
    return {
        "app_name": simpleenvs.get_str("APP_NAME"),
        "debug": simpleenvs.get_bool("DEBUG"),
        "port": simpleenvs.get_int("PORT", 8000)
    }

Environment-Specific Loading

import simpleenvs

# Auto-detect environment
env = os.getenv('ENVIRONMENT', 'development')
simpleenvs.load_dotenv(f'.env.{env}')

# Production with security
simpleenvs.load_dotenv_secure('.env.production')

🆚 SimpleEnvs vs python-dotenv

Feature	python-dotenv	SimpleEnvs
Performance	Baseline	2-40x faster ⚡
Type Safety	Manual casting	Automatic 🎯
Security	Basic	Enterprise-grade 🔒
Memory Isolation	❌	✅ Secure mode
Async Support	❌	✅ Full support
Auto-discovery	❌	✅ Smart scanning
API Compatibility	✅	✅ Drop-in replacement

🛠️ API Reference

Loading Functions

# Simple loading (python-dotenv compatible)
load_dotenv(path=None)                    # Sync
aload_dotenv(path=None)                   # Async

# Secure loading (memory-isolated)  
load_dotenv_secure(path=None, strict=True)

# Advanced loading
simpleenvs.load(path, max_depth=2)        # Async with depth control
simpleenvs.load_sync(path, max_depth=2)   # Sync with depth control
simpleenvs.load_secure(path, strict=True) # Full secure loading

Type-Safe Getters

# Simple access (from os.environ)
get(key, default=None)           # Any type
get_str(key, default=None)       # String
get_int(key, default=None)       # Integer  
get_bool(key, default=None)      # Boolean

# Secure access (memory-isolated)
get_secure(key, default=None)        # Any type
get_str_secure(key, default=None)    # String
get_int_secure(key, default=None)    # Integer
get_bool_secure(key, default=None)   # Boolean

Utility Functions

# Status checks
is_loaded()                      # Simple loader status
is_loaded_secure()               # Secure loader status

# Information
get_info()                       # Library info
get_security_info()              # Security session info
get_all_keys()                   # All loaded keys

# Cleanup
clear()                          # Clear all loaded data

🧪 Testing

Run Tests

# Install with test dependencies
pip install simpleenvs[test]

# Run full test suite  
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=simpleenvs --cov-report=html

Benchmarks

# Performance comparison with python-dotenv
python -m simpleenvs.benchmark

# Quick test (3 rounds)
python -m simpleenvs.benchmark --quick

# Include secure mode testing  
python -m simpleenvs.benchmark --secure

# More rounds for accuracy
python -m simpleenvs.benchmark --rounds 10

Security Testing

# Comprehensive security tests
python -m simpleenvs.vuln_test

# Tests path traversal, injection attacks, memory isolation, etc.
# 51 security tests covering enterprise threat scenarios

🏗️ Use Cases

Development

# Quick setup
from simpleenvs import load_dotenv
load_dotenv()  # Fast, simple, effective

Production Web Apps

# Public config + secure secrets
await simpleenvs.load('config.env')        # Public settings
await simpleenvs.load_secure('secrets.env') # Sensitive data

Enterprise Applications

# Maximum security with monitoring
from simpleenvs import SecureEnvLoader

loader = SecureEnvLoader(session_id="prod-001")
await loader.load_secure()

# Access with logging
secret = loader.get_secure('API_KEY')

# Audit trail
logs = loader.get_access_log()
integrity_ok = loader.verify_file_integrity('.env')

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/vmintf/SimpleEnvs-Python.git
cd SimpleEnvs-Python

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black src/ tests/
isort src/ tests/

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by python-dotenv
• Built with security principles from OWASP
• Performance optimizations inspired by Zig design philosophy
• Project originated from Zig SimpleEnvs

📚 Learn More

• 📖 Full Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📦 PyPI Package

---

Made with ❤️ for the Python community

Simple to use, enterprise-grade security, proven performance 🚀