Environment Variables

20 min read

Quick Overview

Environment variables are how a process inherits configuration from its surroundings — database URLs, ports, API keys, feature flags, and CI/NODE_ENV-style switches. In Node you reach for process.env and often the dotenv package; in Rust you reach for std::env::var and, when you want a .env file or struct-shaped config, the dotenvy and envy crates. This page shows how to read, parse, and validate environment configuration the Rust way, and where the experience diverges sharply from process.env.

The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. The crate examples here use dotenvy 0.15, envy 0.4, and serde 1.0.

Note: Reading the first positional arguments of your program (std::env::args) is a different topic covered under argument parsing — see Argument Parsing with clap. This page is strictly about the process environment (std::env::var and friends).

TypeScript/JavaScript Example

A typical Node service reads configuration from process.env, loads a .env file in development, and supplies defaults inline:

1
// config.ts — run with: npx tsx config.ts
2
// Depends on: npm install dotenv
3
import "dotenv/config"; // loads .env into process.env as a side effect
4

5
interface Config {
6
  databaseUrl: string;
7
  port: number;
8
  logLevel: string;
9
  debug: boolean;
10
}
11

12
function loadConfig(): Config {
13
  const databaseUrl = process.env.DATABASE_URL;
14
  if (!databaseUrl) {
15
    throw new Error("DATABASE_URL is required");
16
  }
17

18
  return {
19
    databaseUrl,
20
    // process.env values are ALWAYS strings | undefined — you must parse.
21
    port: parseInt(process.env.PORT ?? "8080", 10),
22
    logLevel: process.env.LOG_LEVEL ?? "info",
23
    debug: process.env.DEBUG === "true" || process.env.DEBUG === "1",
24
  };
25
}
26

27
const config = loadConfig();
28
console.log(config);

1
$ DATABASE_URL=postgres://localhost/app PORT=3000 DEBUG=1 npx tsx config.ts
2
{
3
  databaseUrl: 'postgres://localhost/app',
4
  port: 3000,
5
  logLevel: 'info',
6
  debug: true
7
}

Three things to internalize about Node’s model, because Rust will challenge each one:

Every value is string | undefined. process.env.PORT is the string "3000", never the number 3000. typeof process.env.PORT prints undefined when unset and "string" otherwise. Parsing and validation are entirely on you, and a typo like PORT=abc silently becomes NaN after parseInt.
Reading and writing process.env is trivial and global. Anyone can do process.env.X = "y" from any module at any time.
dotenv mutates process.env as an import side effect and, by default, does not overwrite variables that are already set.

Rust Equivalent

The same configuration loader in Rust, using std::env::var for reading and dotenvy to load a .env file in development:

1
// Depends on: cargo add dotenvy
2
use std::env;
3
use std::process;
4

5
#[derive(Debug)]
6
struct Config {
7
    database_url: String,
8
    port: u16,
9
    log_level: String,
10
    debug: bool,
11
}
12

13
fn load_config() -> Result<Config, String> {
14
    // Load .env into the process environment if it exists.
15
    // A missing file is fine in production where real env vars are set.
16
    let _ = dotenvy::dotenv();
17

18
    // env::var returns Result<String, VarError>, so a missing required
19
    // value is an honest error, not a silent `undefined`.
20
    let database_url = env::var("DATABASE_URL")
21
        .map_err(|_| "DATABASE_URL is required".to_string())?;
22

23
    // PORT must parse as a u16; we choose a default when it is absent.
24
    let port: u16 = match env::var("PORT") {
25
        Ok(s) => s
26
            .parse()
27
            .map_err(|_| format!("PORT='{s}' is not a valid port number"))?,
28
        Err(_) => 8080,
29
    };
30

31
    let log_level = env::var("LOG_LEVEL").unwrap_or_else(|_| "info".to_string());
32

33
    let debug = env::var("DEBUG")
34
        .map(|v| v == "true" || v == "1")
35
        .unwrap_or(false);
36

37
    Ok(Config {
38
        database_url,
39
        port,
40
        log_level,
41
        debug,
42
    })
43
}
44

45
fn main() {
46
    let config = load_config().unwrap_or_else(|err| {
47
        eprintln!("configuration error: {err}");
48
        process::exit(1);
49
    });
50

51
    println!("{config:#?}");
52
}

1
$ DATABASE_URL=postgres://localhost/app PORT=3000 DEBUG=1 cargo run --quiet
2
Config {
3
    database_url: "postgres://localhost/app",
4
    port: 3000,
5
    log_level: "info",
6
    debug: true,
7
}

The shape is familiar, but every read is a Result you must handle, and PORT is a real u16 — if it does not parse, you find out at startup with a clear message rather than discovering NaN mid-request.

Detailed Explanation

`std::env::var` returns a `Result`, not a string-or-undefined

The single most important difference: env::var(key) has the signature

1
// from the standard library
2
pub fn var<K: AsRef<OsStr>>(key: K) -> Result<String, VarError>

There is no undefined. A missing variable is Err(VarError::NotPresent); a present-but-non-UTF-8 value is Err(VarError::NotUnicode(_)). This forces you to decide, at the call site, what “missing” means — a default, an error, or None.

The idioms map cleanly onto the ?./?? patterns you already know:

1
use std::env;
2

3
fn main() {
4
    // ?? "default"  ->  unwrap_or_else with a closure (avoids allocating when set)
5
    let port = env::var("PORT").unwrap_or_else(|_| "8080".to_string());
6

7
    // optional value  ->  .ok() converts Result into Option
8
    let log_level: Option<String> = env::var("LOG_LEVEL").ok();
9

10
    // "is the flag present at all?"  ->  .is_ok()
11
    let in_ci = env::var("CI").is_ok();
12

13
    // empty-string fallback  ->  unwrap_or_default()
14
    let extra = env::var("EXTRA_ARGS").unwrap_or_default();
15

16
    println!("port={port} log_level={log_level:?} in_ci={in_ci} extra={extra:?}");
17
}

1
$ cargo run --quiet
2
port=8080 log_level=None in_ci=false extra=""
3

4
$ CI=1 EXTRA_ARGS=--fast cargo run --quiet
5
port=8080 log_level=None in_ci=true extra="--fast"

Parsing numbers and booleans

Because env::var yields a String, parsing looks like any other Rust parse. A compact “default if unset or unparseable” reads as a chain:

1
use std::env;
2

3
fn main() {
4
    let port: u16 = env::var("PORT")
5
        .ok()                       // Result -> Option
6
        .and_then(|s| s.parse().ok()) // Option<String> -> Option<u16>
7
        .unwrap_or(8080);           // fall back
8

9
    let debug = env::var("DEBUG")
10
        .map(|v| v == "1" || v == "true")
11
        .unwrap_or(false);
12

13
    println!("port={port} debug={debug}");
14
}

1
$ cargo run --quiet
2
port=8080 debug=false
3

4
$ PORT=abc DEBUG=true cargo run --quiet
5
port=8080 debug=true

Tip: The chain above silently falls back to 8080 when PORT=abc, mirroring Node’s parseInt(...) || 8080. That is convenient but hides typos. For production config, prefer the explicit match from the Rust Equivalent section, which turns PORT=abc into a fatal, descriptive error. Silent fallbacks are how a PORT=80800 typo lands you on the default port in production.

Distinguishing the two failure modes

When you genuinely need to tell “not set” apart from “set to garbage bytes”, match on VarError:

1
use std::env;
2

3
fn main() {
4
    match env::var("CONFIG_PATH") {
5
        Ok(value) => println!("CONFIG_PATH = {value}"),
6
        Err(env::VarError::NotPresent) => println!("CONFIG_PATH is not set"),
7
        Err(env::VarError::NotUnicode(raw)) => {
8
            println!("CONFIG_PATH contains non-UTF-8 bytes: {raw:?}");
9
        }
10
    }
11
}

1
$ cargo run --quiet
2
CONFIG_PATH is not set
3

4
$ CONFIG_PATH=/etc/app.toml cargo run --quiet
5
CONFIG_PATH = /etc/app.toml

If you want the raw bytes regardless of encoding (paths on Linux/macOS can legally be non-UTF-8), use env::var_os, which returns Option<OsString> and never errors:

1
use std::env;
2

3
fn main() {
4
    // var_os never fails on encoding; it just gives you the raw OsString.
5
    let home = env::var_os("HOME");
6
    println!("HOME present: {}", home.is_some());
7
}

1
$ cargo run --quiet
2
HOME present: true

Loading a `.env` file with dotenvy

dotenvy is the maintained successor to the older dotenv crate. Add it and call dotenvy::dotenv() once, early in main:

1
cargo add dotenvy

Given a .env file in the working directory:

1
DATABASE_URL=postgres://localhost/myapp
2
PORT=4000
3
# comment lines are ignored
4
LOG_LEVEL=debug

1
use std::env;
2

3
fn main() {
4
    // Returns Ok(path) with the file it loaded, or Err if no .env was found.
5
    match dotenvy::dotenv() {
6
        Ok(path) => println!("loaded env from {}", path.display()),
7
        Err(e) => println!("no .env loaded: {e}"),
8
    }
9

10
    let url = env::var("DATABASE_URL").unwrap_or_else(|_| "<unset>".into());
11
    let port = env::var("PORT").unwrap_or_else(|_| "<unset>".into());
12
    println!("DATABASE_URL = {url}");
13
    println!("PORT         = {port}");
14
}

1
$ cargo run --quiet
2
loaded env from /path/to/project/.env
3
DATABASE_URL = postgres://localhost/myapp
4
PORT         = 4000
5

6
$ PORT=9999 cargo run --quiet
7
loaded env from /path/to/project/.env
8
DATABASE_URL = postgres://localhost/myapp
9
PORT         = 9999

Notice the second run: the real environment variable PORT=9999 wins over the .env value 4000. Like Node’s dotenv, dotenvy::dotenv() does not overwrite variables that are already present in the environment. That precedence is exactly what you want: real env vars (set by your shell, Docker, or systemd) override the development .env defaults.

Note: dotenvy::dotenv() returns an Err when no .env file exists. In production you usually want that to be a no-op, so discard it with let _ = dotenvy::dotenv();. Do not unwrap() it, or your binary will refuse to start anywhere a .env is absent.

Struct-shaped config with envy

Reading a dozen variables by hand gets tedious. The envy crate deserializes the environment straight into a serde struct, applying defaults and type-checking each field — the closest Rust equivalent to validating process.env with a schema library like zod or envalid in Node.

1
cargo add envy
2
cargo add serde --features derive

1
use serde::Deserialize;
2
use std::process;
3

4
#[derive(Debug, Deserialize)]
5
struct Config {
6
    // Required: deserialization fails if APP_DATABASE_URL is missing.
7
    database_url: String,
8
    // Default applied when APP_PORT is absent.
9
    #[serde(default = "default_port")]
10
    port: u16,
11
    // Option becomes None when APP_LOG_LEVEL is absent.
12
    log_level: Option<String>,
13
    // bool parsing via serde accepts only "true"/"false" (not "1"/"0").
14
    #[serde(default)]
15
    debug: bool,
16
}
17

18
fn default_port() -> u16 {
19
    8080
20
}
21

22
fn main() {
23
    // envy maps APP_DATABASE_URL -> database_url, APP_PORT -> port, etc.
24
    let config = envy::prefixed("APP_")
25
        .from_env::<Config>()
26
        .unwrap_or_else(|err| {
27
            eprintln!("configuration error: {err}");
28
            process::exit(1);
29
        });
30

31
    println!("{config:#?}");
32
}

1
$ APP_DATABASE_URL=postgres://db/app APP_PORT=5000 APP_LOG_LEVEL=info APP_DEBUG=true cargo run --quiet
2
Config {
3
    database_url: "postgres://db/app",
4
    port: 5000,
5
    log_level: Some(
6
        "info",
7
    ),
8
    debug: true,
9
}
10

11
$ APP_DATABASE_URL=postgres://db/app cargo run --quiet
12
Config {
13
    database_url: "postgres://db/app",
14
    port: 8080,
15
    log_level: None,
16
    debug: false,
17
}
18

19
$ cargo run --quiet
20
configuration error: missing value for field database_url
21

22
$ APP_DATABASE_URL=x APP_PORT=notanumber cargo run --quiet
23
configuration error: invalid digit found in string while parsing value 'notanumber' provided by PORT

envy lowercases variable names and strips the prefix to match field names: APP_DATABASE_URL → database_url. A missing required field, or a value that does not parse to the field’s type, is a single descriptive Err — no per-field plumbing. envy even splits a comma-separated value into a Vec:

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Settings {
5
    host: String,
6
    #[serde(default)]
7
    allowed_origins: Vec<String>,
8
}
9

10
fn main() {
11
    let s = envy::prefixed("SVC_").from_env::<Settings>().unwrap();
12
    println!("host = {}", s.host);
13
    println!("origins = {:?}", s.allowed_origins);
14
}

1
$ SVC_HOST=0.0.0.0 SVC_ALLOWED_ORIGINS="https://a.com,https://b.com" cargo run --quiet
2
host = 0.0.0.0
3
origins = ["https://a.com", "https://b.com"]

Key Differences

Aspect	Node (`process.env`)	Rust (`std::env`)
Read a variable	`process.env.KEY` → `string \| undefined`	`env::var("KEY")` → `Result<String, VarError>`
Missing variable	`undefined` (silent)	`Err(VarError::NotPresent)` (must handle)
Type	Always `string`	Always `String`; you `parse()` to a real type
Default value	`process.env.KEY ?? "x"`	`env::var("KEY").unwrap_or_else(\|_\| "x".into())`
Optional value	truthiness checks	`env::var("KEY").ok()` → `Option<String>`
Non-UTF-8 values	coerced/garbled	explicit `VarError::NotUnicode`, or use `var_os`
Writing a variable	`process.env.KEY = "v"` (anytime)	`unsafe { env::set_var(..) }` (edition 2024)
`.env` files	`dotenv` (import side effect)	`dotenvy::dotenv()` (explicit call)
Schema validation	`zod` / `envalid` (external)	`envy` + `serde` derive
`.env` vs real env	real env wins (dotenv default)	real env wins (dotenvy default)

Why is `set_var` `unsafe` now?

This surprises everyone coming from JavaScript. In the latest stable edition (2024), std::env::set_var and remove_var are unsafe functions:

1
use std::env;
2

3
fn main() {
4
    // SAFETY: called before any threads are spawned, so no other thread
5
    // can be reading the environment concurrently.
6
    unsafe {
7
        env::set_var("APP_MODE", "production");
8
    }
9
    println!("APP_MODE = {}", env::var("APP_MODE").unwrap());
10
}

1
$ cargo run --quiet
2
APP_MODE = production

The reason is genuine: on Unix, the C getenv/setenv machinery underneath is not thread-safe. One thread writing the environment while another reads it is a data race that can crash or corrupt memory. JavaScript hides this because Node is single-threaded for process.env. Rust makes the danger visible: mutate the environment only at startup, before spawning threads, and mark it unsafe to acknowledge the contract. In practice you rarely set environment variables at runtime at all — prefer passing config values through your own data structures.

The environment is a snapshot, not a live binding

Both languages read the environment that existed when the process started (plus any in-process mutations). Neither sees changes a parent shell makes after launch. The difference is that Rust’s standard library, and most config crates, encourage you to read the environment once into a typed struct at startup, then pass that struct around — rather than calling env::var scattered throughout the code the way process.env.X tends to proliferate in Node.

Common Pitfalls

Pitfall 1: Calling `set_var` without `unsafe`

Code ported from a single-threaded mindset trips on edition 2024 immediately:

1
use std::env;
2

3
fn main() {
4
    // does not compile (error[E0133]: call to unsafe function is unsafe)
5
    env::set_var("APP_MODE", "production");
6
    println!("{}", env::var("APP_MODE").unwrap());
7
}

The real compiler error:

1
error[E0133]: call to unsafe function `set_var` is unsafe and requires unsafe block
2
 --> src/main.rs:5:5
3
  |
4
5 |     env::set_var("APP_MODE", "production");
5
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ call to unsafe function
6
  |
7
  = note: consult the function's documentation for information on how to avoid undefined behavior
8

9
For more information about this error, try `rustc --explain E0133`.

The fix is to wrap it in an unsafe { .. } block and ensure you only do it before any threads start. Better yet, avoid mutating the environment entirely.

Pitfall 2: `unwrap()`-ing a missing variable

env::var("KEY").unwrap() is the Rust equivalent of assuming process.env.KEY is always defined. If the variable is absent, the program panics:

1
use std::env;
2

3
fn main() {
4
    // Panics at runtime if API_KEY is not set.
5
    let key = env::var("API_KEY").unwrap();
6
    println!("{key}");
7
}

1
$ cargo run --quiet
2
thread 'main' panicked at src/main.rs:5:35:
3
called `Result::unwrap()` on an `Err` value: NotPresent
4
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

NotPresent is a cryptic panic message for an operator who forgot to export a variable. Prefer unwrap_or_else with a clear eprintln! + process::exit, or expect("API_KEY must be set"), or — best — bundle required variables into an envy struct so the error names the field.

Pitfall 3: `unwrap()`-ing `dotenvy::dotenv()` in production

1
fn main() {
2
    // logic bug: panics anywhere there is no .env file (i.e. production).
3
    dotenvy::dotenv().unwrap();
4
}

.env files are a development convenience and are typically git-ignored and absent in production, where config comes from real environment variables. unwrap() here turns a normal situation into a crash. Use let _ = dotenvy::dotenv(); (or dotenvy::dotenv().ok();) so a missing file is a silent no-op.

Pitfall 4: Expecting silent string coercion

In Node, process.env.PORT + 1 produces the string "30001" because + concatenates. In Rust, env::var("PORT") is a String; you cannot do arithmetic on it without an explicit parse(). This is a feature: it stops the classic JavaScript bug where a numeric env var silently becomes string-concatenated. But it means every numeric or boolean variable needs a deliberate parse step, as shown above.

Pitfall 5: `.env` precedence confusion

A frequent question: “I set PORT in .env but it’s using the old value.” Remember that any variable already present in the real environment overrides .env. If your shell exported PORT in a previous session, or your IDE injects it, the .env line is ignored. To see what is actually in effect, print the resolved config at startup (as the Real-World Example does).

Best Practices

Read the environment once, into a typed struct. Parse env::var/envy results into a Config struct at startup and pass it (or an Arc<Config>) around. Scattering env::var("X") calls through the codebase is the Rust version of process.env.X sprawl and makes config impossible to audit.
Fail fast with a clear message. Validate all required variables in main before doing real work. A missing DATABASE_URL should produce one readable line and a non-zero exit code, not a panic 200 lines later. See Cross-Platform Considerations for choosing meaningful exit codes.
Make .env loading optional and explicit. Call let _ = dotenvy::dotenv(); early; never unwrap() it. Keep .env out of version control and commit a .env.example listing required keys instead.
Prefer envy for anything beyond a couple of variables. Struct deserialization gives you defaults, type-checking, and field-named errors for free, and reads like a schema.
Use a consistent prefix (APP_, SVC_, your tool’s name) so your variables do not collide with the dozens of unrelated ones already in the environment, and so envy::prefixed("APP_") can scope cleanly.
Never log secrets. When you print resolved config for debugging, redact API_KEY, DATABASE_URL passwords, and tokens. Rust will happily Debug-print a secret-bearing struct; that is on you to prevent.
Reach for the config crate when you need layering. For tools that merge defaults + a config file + environment + flags, the config crate composes all of these; envy alone is best when the environment is your single source of truth.

Real-World Example

A small file-upload service that loads .env in development, reads APP_-prefixed configuration into a struct with sensible defaults, validates it, and exits with a meaningful code on misconfiguration:

1
// Depends on: cargo add dotenvy envy ; cargo add serde --features derive
2
use serde::Deserialize;
3
use std::process;
4

5
#[derive(Debug, Deserialize)]
6
struct Config {
7
    database_url: String,
8
    #[serde(default = "default_port")]
9
    port: u16,
10
    #[serde(default = "default_max_upload")]
11
    max_upload_mb: u32,
12
    #[serde(default)]
13
    verbose: bool,
14
}
15

16
fn default_port() -> u16 {
17
    8080
18
}
19

20
fn default_max_upload() -> u32 {
21
    10
22
}
23

24
impl Config {
25
    /// Load `.env` (if present), then read `APP_`-prefixed variables.
26
    fn load() -> Result<Self, envy::Error> {
27
        // Ignore a missing .env file; only deserialization errors propagate.
28
        let _ = dotenvy::dotenv();
29
        envy::prefixed("APP_").from_env::<Config>()
30
    }
31
}
32

33
fn main() {
34
    let config = Config::load().unwrap_or_else(|err| {
35
        eprintln!("failed to load configuration: {err}");
36
        eprintln!("hint: set APP_DATABASE_URL (and optionally APP_PORT, APP_MAX_UPLOAD_MB)");
37
        // 78 = EX_CONFIG from sysexits.h: a configuration error.
38
        process::exit(78);
39
    });
40

41
    println!("starting uploader on port {}", config.port);
42
    println!("  database: {}", config.database_url);
43
    println!("  max upload: {} MB", config.max_upload_mb);
44
    println!("  verbose: {}", config.verbose);
45
    // ... start the real server with `config` here ...
46
}

With a development .env:

1
APP_DATABASE_URL=postgres://localhost/uploader
2
APP_PORT=8000
3
APP_MAX_UPLOAD_MB=25

1
$ cargo run --quiet
2
starting uploader on port 8000
3
  database: postgres://localhost/uploader
4
  max upload: 25 MB
5
  verbose: false
6

7
$ APP_PORT=9000 APP_VERBOSE=true cargo run --quiet
8
starting uploader on port 9000
9
  database: postgres://localhost/uploader
10
  max upload: 25 MB
11
  verbose: true
12

13
$ cargo run --quiet   # no .env, no env vars
14
failed to load configuration: missing value for field database_url
15
hint: set APP_DATABASE_URL (and optionally APP_PORT, APP_MAX_UPLOAD_MB)
16
$ echo $?
17
78

The second run shows real env vars overriding .env; the third shows a clean, actionable failure with a conventional exit code instead of a panic.

Exercises

Exercise 1: A validated numeric variable with a default

Difficulty: Beginner

Objective: Practice converting env::var into a parsed, validated value with a fallback, the way you would harden a Node parseInt(process.env.X) call.

Instructions: Write a program that reads a WORKERS environment variable. If it is set to a valid integer of at least 1, use it. If it is set but invalid (zero, negative, or non-numeric), print a warning to stderr and fall back to 1. If it is unset, default to 4. Print spawning N workers.

1
use std::env;
2

3
fn main() {
4
    let workers: usize = /* ??? read, parse, validate, default */ 0;
5
    println!("spawning {workers} workers");
6
}

Solution

1
use std::env;
2

3
fn main() {
4
    let workers: usize = match env::var("WORKERS") {
5
        Ok(s) => match s.parse::<usize>() {
6
            Ok(n) if n >= 1 => n,
7
            Ok(_) => {
8
                eprintln!("WORKERS must be at least 1; using 1");
9
                1
10
            }
11
            Err(_) => {
12
                eprintln!("WORKERS='{s}' is not a number; using 1");
13
                1
14
            }
15
        },
16
        Err(_) => 4, // sensible default when unset
17
    };
18
    println!("spawning {workers} workers");
19
}

Verified output:

1
$ cargo run --quiet
2
spawning 4 workers
3

4
$ WORKERS=8 cargo run --quiet
5
spawning 8 workers
6

7
$ WORKERS=0 cargo run --quiet
8
WORKERS must be at least 1; using 1
9
spawning 1 workers
10

11
$ WORKERS=foo cargo run --quiet
12
WORKERS='foo' is not a number; using 1
13
spawning 1 workers

Exercise 2: Struct-shaped config with envy

Difficulty: Intermediate

Objective: Replace hand-rolled env::var calls with an envy-deserialized struct, including a default and a comma-separated list.

Instructions: Define a Settings struct with fields host: String (required), port: u16 (default 3000), and allowed_origins: Vec<String> (default empty, populated from a comma-separated value). Read it with the SVC_ prefix and print each field. Add cargo add envy and cargo add serde --features derive.

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Settings {
5
    // TODO: host, port (default 3000), allowed_origins (default empty)
6
}
7

8
fn main() {
9
    // TODO: envy::prefixed("SVC_").from_env::<Settings>() and print fields
10
}

Solution

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Settings {
5
    host: String,
6
    #[serde(default = "default_port")]
7
    port: u16,
8
    // envy splits a comma-separated value into a Vec.
9
    #[serde(default)]
10
    allowed_origins: Vec<String>,
11
}
12

13
fn default_port() -> u16 {
14
    3000
15
}
16

17
fn main() {
18
    match envy::prefixed("SVC_").from_env::<Settings>() {
19
        Ok(s) => {
20
            println!("host = {}", s.host);
21
            println!("port = {}", s.port);
22
            println!("origins = {:?}", s.allowed_origins);
23
        }
24
        Err(e) => eprintln!("config error: {e}"),
25
    }
26
}

Verified output:

1
$ SVC_HOST=0.0.0.0 SVC_ALLOWED_ORIGINS="https://a.com,https://b.com" cargo run --quiet
2
host = 0.0.0.0
3
port = 3000
4
origins = ["https://a.com", "https://b.com"]
5

6
$ SVC_HOST=localhost cargo run --quiet
7
host = localhost
8
port = 3000
9
origins = []

Exercise 3: Layered precedence — flag beats env beats default

Difficulty: Advanced

Objective: Implement the common configuration precedence rule “command-line flag > environment variable > built-in default” by hand, so you understand what clap + env layering does under the hood.

Instructions: Resolve a log level from three sources, highest priority first: a --log-level <value> (or --log-level=<value>) command-line argument, then the LOG_LEVEL environment variable, then the default "info". Use std::env::args for the flag and std::env::var for the variable. Print log level = X.

1
use std::env;
2

3
fn resolve_log_level() -> String {
4
    // TODO: check --log-level arg, then LOG_LEVEL env, then default "info"
5
    String::from("info")
6
}
7

8
fn main() {
9
    println!("log level = {}", resolve_log_level());
10
}

Solution

1
use std::env;
2

3
fn resolve_log_level() -> String {
4
    // 1. Highest priority: a --log-level <value> CLI argument.
5
    let mut args = env::args().skip(1);
6
    while let Some(arg) = args.next() {
7
        if arg == "--log-level" {
8
            if let Some(v) = args.next() {
9
                return v;
10
            }
11
        } else if let Some(v) = arg.strip_prefix("--log-level=") {
12
            return v.to_string();
13
        }
14
    }
15
    // 2. Next: the LOG_LEVEL environment variable.
16
    // 3. Fallback: a built-in default.
17
    env::var("LOG_LEVEL").unwrap_or_else(|_| "info".to_string())
18
}
19

20
fn main() {
21
    println!("log level = {}", resolve_log_level());
22
}

Verified output:

1
$ cargo run --quiet
2
log level = info
3

4
$ LOG_LEVEL=warn cargo run --quiet
5
log level = warn
6

7
$ LOG_LEVEL=warn cargo run --quiet -- --log-level debug
8
log level = debug
9

10
$ cargo run --quiet -- --log-level=trace
11
log level = trace

In a real tool you would let clap parse the flag and supply env = "LOG_LEVEL" on the argument so this layering is declarative — see clap derive API. Doing it by hand here shows exactly which source wins.

Next: Cross-Platform Considerations — line endings, path separators, cfg!(windows), and exit codes.

Environment Variables

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

std::env::var returns a Result, not a string-or-undefined

Parsing numbers and booleans

Distinguishing the two failure modes

Loading a .env file with dotenvy

Struct-shaped config with envy

Key Differences

Why is set_var unsafe now?

The environment is a snapshot, not a live binding

Common Pitfalls

Pitfall 1: Calling set_var without unsafe

Pitfall 2: unwrap()-ing a missing variable

Pitfall 3: unwrap()-ing dotenvy::dotenv() in production

Pitfall 4: Expecting silent string coercion

Pitfall 5: .env precedence confusion

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A validated numeric variable with a default

Exercise 2: Struct-shaped config with envy

Exercise 3: Layered precedence — flag beats env beats default

`std::env::var` returns a `Result`, not a string-or-undefined

Loading a `.env` file with dotenvy

Why is `set_var` `unsafe` now?

Pitfall 1: Calling `set_var` without `unsafe`

Pitfall 2: `unwrap()`-ing a missing variable

Pitfall 3: `unwrap()`-ing `dotenvy::dotenv()` in production

Pitfall 5: `.env` precedence confusion