.env Files — Aquilia Documentation
Comprehensive guide and documentation for .env Files in the Aquilia framework. View API reference, examples, and implementation patterns.
.env Files aquilia.dotenv — zero-dependency, production-ready .env loader Aquilia ships its own DotEnv loader — no python-dotenv required. It loads .env files automatically before any Env or Secret binding is first resolved. It supports variable interpolation, multiline values, the export keyword, and escape sequences in double-quoted strings. Values already in the process environment are never overwritten by default — Docker, Kubernetes, and CI/CD injected secrets always win. , , ', sub: 'env-specific', color: '#f59e0b' }, .local', sub: 'local env-specific', color: '#3b82f6' }, , ].map(( , i) => ( ))} ← lower priority · · · · · · · · · · · · higher priority → Quick start In most apps you never call load_dotenv() at all — loading fires automatically the first time any Env or Secret descriptor is resolved. If you need explicit control: Complete syntax reference Aquilia's parser is a strict, safe subset of the de-facto .env standard. No shell expansion, no subshells, no eval(). File precedence and environment cascade Aquilia searches for files in this exact order, resolved from the workspace root (the directory containing workspace.py). Later files override earlier ones. os.environ always wins regardless of override — that flag only controls whether dotenv values overwrite other dotenv-sourced values. File Priority Commit? Purpose ', '3', 'Usually yes', 'Environment-specific values (.env.dev, .env.staging, .env.prod). Non-sensitive settings committed here.'], ['.env. .local', '4 — Highest', 'No — gitignore', 'Local per-environment overrides for developer machines. Never committed.'], ['config/.env', 'Parallel', 'Yes', 'Alternative location under config/ — same rules as .env.'], ['config/.env. ', 'Parallel', 'Usually yes', 'Alternative location for env-specific config under config/.'], ['os.environ (process)', 'Always wins', '—', 'CI/CD, Docker, Kubernetes. Never overwritten by .env files (override=False default).'], ['.env.example', 'Never loaded', 'Yes', 'Template checked into VCS for onboarding. Not a config source — copy to .env to use.'], ].map(([file, priority, commit, purpose], i) => ( ))} Add .env.local and .env.*.local to your .gitignore. These files are for machine-specific secrets and should never reach version control. Workspace root discovery Before loading any file, Aquilia resolves the workspace root directory. The search order is: AQUILIA_WORKSPACE environment variable — if set, used directly as the root path. Current working directory (cwd) — if it contains workspace.py. Walk up the directory tree — up to 10 levels, checking each parent for workspace.py. Fall back to cwd if no workspace.py is found anywhere. The environment mode used for '} substitution in file paths is resolved from AQUILIA_ENV → AQ_ENV → "dev". The value "production" is normalised to "prod" automatically. DotEnv class — parse and load The DotEnv class exposes two independent operations: parse (reads file → returns dict, no side effects) and load (reads file → writes to os.environ). Use parse when you need to inspect values without affecting the running process. DotEnvLoader — singleton for automatic loading DotEnvLoader is the framework's internal singleton that ensures .env files are loaded exactly once, thread-safely, regardless of how many concurrent requests access Env descriptors simultaneously. It uses a threading.Lock to protect the loaded-once state. Class method Returns Description ))} Module-level functions These are convenience wrappers around DotEnv and DotEnvLoader for the most common use cases. Import them directly from aquilia.dotenv. Function Returns Description ))} AquilaConfig.Dotenv — fine-grained policy For full control over which files are loaded and in what order, define a nested Dotenv class inside your AquilaConfig subclass. This is the declarative approach and the one that works best with IDE autocompletion. Variable interpolation Interpolation expands '} and $VAR references inside values. The resolution order within a single file is: already-resolved keys from earlier lines → later keys in the same file → os.environ. This means forward references don't resolve — order matters. Security guarantees — ))} Recommended .gitignore entries Typical project layout REDIS_URL=redis://localhost:6379/0`} /> Testing with .env files Reset loader state between tests using the autouse fixture pattern. Because DotEnvLoader.reset() does not remove values from os.environ, you also need monkeypatch to fully isolate environment variable state. ))} )
Go to Homepage