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.
let name = std::env::var("USER").unwrap_or_else(|_| "stranger".to_string());
Try it
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.
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)orskip(1)over indexing; users run programs with no arguments. - Use
var_osorargs_osfor 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
varthroughout the code. set_current_diris process-wide and not thread-safe in spirit; prefer passing explicit paths.unsafeonset_vararrived with edition 2024 (Rust 1.85); in older editions it is a safe function with the same underlying hazard.