envigil
Keep vigil over your environment.
Load, parse, and validate environment variables with zero dependencies and first-class error reporting.
Why envigil?
std::env |
envy |
envconfig |
dotenvy |
figment |
config |
envigil |
|
|---|---|---|---|---|---|---|---|
| Zero dependencies | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Typed parsing | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| Semantic validation | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Multi-error reporting | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Secret redaction | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
.env file support |
❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ (feature) |
| Derive macro | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ (feature) |
Testing without std::env |
❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
envigil is not a replacement for figment or config (layered providers,
async, file formats). It is a lightweight alternative to envy / envconfig
for those who need validation, multi-error reporting, and secret redaction
without pulling in dependencies.
The core crate is std-only. No serde, no syn, no anyhow. Proc-macro and
.env support are opt-in feature flags.
Quick start
[]
= "0.2"
Builder API
use ;
use validate;
use Duration;
Derive API
[]
= { = "0.2", = ["derive"] }
use ;
let cfg = from_env?;
Generated constructors:
| Constructor | Description |
|---|---|
Config::from_env() |
Loads from the process environment. |
Config::from_map(values) |
Uses an in-memory map as a fallback. Useful for tests. Real environment variables still take precedence. |
Field attributes:
| Attribute | Description |
|---|---|
#[env(default = "value")] |
Parse and use this fallback when the variable is absent. |
#[env(secret)] |
Wrap the parsed value in Secret<T>. |
#[env(parse_with = path)] |
Use a custom parser fn(&str) -> Result<T, String>. |
#[env(rename = "VAR_NAME")] |
Use exactly this environment variable name. The struct-level prefix is not applied. |
#[env(validate(range(1..=128)))] |
Add a validator. Bare built-in validators resolve as envigil::validate::<validator>. |
#[env(skip)] |
Do not read from environment; initialize the field from Default::default(). |
Multiple validators can be attached:
email: String,
Testing without std::env
EnvSource::from_map (and the derived Config::from_map) loads values from an
in-memory map, so tests do not need unsafe { std::env::set_var(...) } and do
not race with each other:
let cfg = from_map
.declare
.load?;
assert_eq!;
Priority: std::env > .env file > from_map > default. The real
environment always wins.
Error output
All errors are collected and reported together:
environment configuration failed (2 errors)
┌─ APP_PORT
│
│ value 99999 is out of range 1..=65535
┌─ APP_DATABASE_URL
│
│ environment variable 'APP_DATABASE_URL' is required but not set
│ hint: set APP_DATABASE_URL or provide a .env file
Validation
Built-in validators:
| Validator | Description |
|---|---|
range(1..=65535) |
Number within an inclusive range |
not_empty() |
Non-empty string |
contains("@") |
Contains a substring |
starts_with("postgres://") |
Starts with a prefix |
ends_with(".rs") |
Ends with a suffix |
length(1..=255) |
String or collection length within a range |
ip() |
Valid IP address (v4 or v6) |
file_exists() |
Path exists on the filesystem |
Custom validators — any closure via validate_with, or a Validator<T> impl:
new
.validate_with
Parse helpers
| Function | Input | Output |
|---|---|---|
parse::secs("30") |
Seconds | Duration |
parse::millis("500") |
Milliseconds | Duration |
parse::duration("5m 30s") |
Units: ms, s, m, h |
Duration |
parse::bytes("10MB") |
B/KB/MB/GB, KiB/MiB/GiB |
u64 |
parse::flag("yes") |
true/1/yes/on, false/0/no/off |
bool |
parse::list("a, b") |
Comma-separated | Vec<String> |
parse::list_sep(';') |
Custom separator | Vec<String> |
parse::socket_addr("0.0.0.0:8080") |
Socket address (IPv4/IPv6) | SocketAddr |
Secret handling
Variables marked .secret() are stored as Secret<T>:
Debug/Displayprint[REDACTED]- Inner value is accessible only via
.expose() get::<String>()on a secret variable fails — useget::<Secret<String>>()
let url: & = cfg.get?;
let raw: &str = url.expose; // explicit opt-in
.env file support
[]
= { = "0.2", = ["dotenv"] }
let cfg = new
.dotenv // loads .env from CWD (optional)
.dotenv_path // or a specific path
.declare
.load?;
Real environment variables always take priority over .env entries. Missing
files are silently ignored. std::env is never mutated.
Feature flags
| Feature | Default | Adds |
|---|---|---|
derive |
❌ | #[derive(EnvConfig)] (pulls envigil-derive) |
dotenv |
❌ | .env file loading (own parser, no external deps) |
With no features enabled, envigil has zero dependencies.
Minimum Supported Rust Version
1.85.0 (edition 2024). MSRV bumps come with a minor version bump and are noted in the changelog.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.