dotenv Rust Library

The most common way to use this library is to call dotenv::dotenv() at the start of your application. This loads environment variables from a .env file located in the current directory or any of its parent directories. Once loaded, these variables are merged with the existing OS environment variables and can be accessed using standard library methods like std::env::var or std::env::vars.

extern crate dotenv;

use dotenv::dotenv;
use std::env;

fn main() {
    // Load the .env file. .ok() is used to ignore errors if the file is missing.
    dotenv().ok();

    for (key, value) in env::vars() {
        println!("{}: {}", key, value);
    }
}

The dotenv_codegen crate provides the dotenv! macro. This macro behaves like the standard env! macro but attempts to load values from a .env file at compile time. This is useful for embedding configuration directly into your binary.

// 1. Add dotenv_codegen to your Cargo.toml dependencies

// 2. Add this to the top of your crate
#[macro_use]
extern crate dotenv_codegen;

fn main() {
  // 3. Use the macro to fetch a value at compile time
  println!("{}", dotenv!("MEANING_OF_LIFE"));
}

The discovery process follows a recursive upward search pattern:

1. It checks if the filename exists within the provided directory.
2. If the path exists and is a file, it returns that path.
3. If the file is not found, it moves to the parent() directory and repeats the process.
4. The search continues until the file is found or the filesystem root is reached. If the root is reached without finding the file, it returns an io::ErrorKind::NotFound error.

If you need more control than the default behavior, use the following methods to specify exactly which file to load:

• from_filename(filename): Loads variables from a specific filename.
• from_path(path): Loads variables from a specific file path.

A .env file consists of key-value pairs. Lines can be commented out using #. You can optionally prefix lines with export to make the file compatible with shell sourcing.

# a comment, will be ignored
REDIS_ADDRESS=localhost:6379
MEANING_OF_LIFE=42

# Optional export prefix for shell sourcing
export API_KEY=secret_value

If the parser encounters an invalid line format, it returns an Error::LineParse. This error includes the original line content and the character position (pos) where the parsing failed.

Common causes for LineParse errors:

• Invalid Key: Starting a key with a dot . or a non-alphabetic character.
• Unterminated Quotes: Opening a ' or " but not closing it before the end of the line.
• Invalid Escapes: Using a backslash \ followed by a character that is not a recognized escape sequence (e.g., \f is invalid, but \n is valid).
• Malformed Substitution: Using ${ without a closing }.

The Iter::load method consumes an Iter instance and attempts to set environment variables in the current process. It iterates through the parsed key-value pairs and calls std::env::set_var for each pair, but only if the variable is not already set in the environment. This ensures that existing system environment variables take precedence over those defined in the .env file.

// Assuming 'reader' is an object implementing std::io::Read (e.g., a File or Cursor)
let iter = Iter::new(reader);
iter.load()?;

The Iter struct implements the Iterator trait, allowing you to manually traverse the key-value pairs parsed from a reader. Each item yielded by the iterator is a Result<(String, String)>. This is useful if you want to inspect or transform the variables before applying them to the environment.

for item in iter {
    let (key, value) = item?;
    println!("{}={}", key, value);
}

Use dotenv::from_filename(filename) to search for a specific file (e.g., custom.env) in the current directory or its parents. This is useful when you use non-standard naming conventions for your environment files.

use dotenv;

dotenv::from_filename("custom.env").ok();