Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

The std::env module

Reference for std::env: command-line arguments, environment variables, VarError, set_var and remove_var (unsafe in edition 2024), current_dir and temp_dir.

std::env gives a program access to its surroundings: the command-line arguments it was started with, its environment variables, its current working directory and a few well-known directories such as the temporary directory.

Arguments come from env::args(), an iterator of Strings whose first element is conventionally the program's own name. Variables are read with env::var("NAME"), which returns a Result because the variable may be missing or may not be valid Unicode.

Rust
let name = std::env::var("USER").unwrap_or_else(|_| "stranger".to_string());

Try it

Rust Arguments and variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Changing the environment (unsafe in edition 2024)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Function Signature (simplified) Description
args fn args() -> Args Iterator of String; panics during iteration if an argument is not valid Unicode.
args_os fn args_os() -> ArgsOs Iterator of OsString; never panics.
var fn var<K: AsRef<OsStr>>(key: K) -> Result<String, VarError> Read one variable.
var_os fn var_os(key) -> Option<OsString> Read without requiring Unicode.
vars, vars_os iterators All variables; vars panics on non-Unicode data.
set_var, remove_var unsafe fn(key, value) / unsafe fn(key) Modify the process environment (unsafe since edition 2024).
current_dir fn current_dir() -> io::Result<PathBuf> Working directory.
set_current_dir fn set_current_dir(path) -> io::Result<()> Change it for the whole process.
current_exe fn current_exe() -> io::Result<PathBuf> Path of the running executable.
temp_dir, home_dir -> PathBuf / -> Option<PathBuf> Temporary directory; home_dir is best avoided (platform quirks).
consts::OS, ARCH, FAMILY &'static str Constants such as "linux", "x86_64", "unix".

VarError has two variants: NotPresent and NotUnicode(OsString).

Errors and edge cases: an empty variable is Ok(""), not NotPresent. set_var panics if the key is empty or contains = or a NUL byte; the value must not contain NUL.

Usage notes

  • For anything beyond a couple of flags, use an argument parser in a real project; this module only hands you the raw strings.
  • Prefer args().nth(1) or skip(1) over indexing; users run programs with no arguments.
  • Use var_os or args_os for file paths, which can legally be non-UTF-8 on Unix.
  • Environment changes affect only the current process and the children it starts afterward, never the parent shell.
  • Reading variables at startup into a config struct is easier to test than calling var throughout the code.
  • set_current_dir is process-wide and not thread-safe in spirit; prefer passing explicit paths.
  • unsafe on set_var arrived with edition 2024 (Rust 1.85); in older editions it is a safe function with the same underlying hazard.