GNU env -0: NUL-Safe Environment Snapshots and Exact Replay

An environment dump looks like a list of NAME=value lines, but a newline is legal inside a value. Ordinary env output can therefore be ambiguous to a line-oriented parser: one variable may appear to be several records. GNU Coreutils provides env -0 (--null) to terminate each emitted record with NUL instead. Coreutils 9.12 adds the matching --env0-from=FILE input interface, allowing a deliberately captured environment stream to be replayed for a child process.

This is a byte-framing and process-launch feature, not a way to sanitize an environment or create a secret-safe snapshot. The stream may contain credentials and other inherited values. Use the format for controlled, allowlisted tests and machine interfaces; do not casually archive a developer shell’s complete environment in a CI artifact or support bundle.

First distinguish env output from command execution

GNU env can set or unset variables and then launch a command. If no command follows the environment assignments, it prints the resulting environment. --null changes the record terminator in that print mode. It is not a request to run a command whose standard output should somehow be NUL-terminated: Coreutils 9.12 rejects env -0 command because the option applies to environment output, not to the command being launched.

Options must come before operands. This is why the NUL option belongs before any NAME=value operands:

env --null APP_MODE=fixture

The command prints the resulting environment and exits. It does not change the parent shell’s variables. Only values in the process environment are represented; an unexported shell variable is not included merely because it exists in the interactive shell.

Why NUL is the record boundary

An environment entry is represented as a NUL-terminated string, so the entry cannot itself contain an embedded NUL byte. A newline can be part of a value, which makes newline-delimited output unsuitable as an unambiguous record protocol. GNU env -0 writes each complete environment entry followed by NUL; an equals sign after the first separator belongs to the value, not to another field.

Use a consumer that reads bytes and splits on NUL. The small fixture below starts with an empty environment, adds a value containing both a newline and an additional equals sign, and prints only a validation message. It does not dump the full environment or expose the value in its output:

value=$(printf 'line one\nline two=tail')

env -i -0 "AUDIT_VALUE=$value" |
python3 -c '
import sys

data = sys.stdin.buffer.read()
if data and not data.endswith(b"\0"):
    raise SystemExit("truncated NUL-delimited stream")

records = data[:-1].split(b"\0") if data else []
values = []
for record in records:
    name, separator, value = record.partition(b"=")
    if separator and name == b"AUDIT_VALUE":
        values.append(value)

if values != [b"line one\nline two=tail"]:
    raise SystemExit("environment value did not round-trip")

print("NUL framing preserved one value with an embedded newline")
'

partition(b"=") splits only at the first equals sign. A generic split(b"=") would incorrectly turn values containing = into extra fields. The example reads the stream as bytes because environment data is not guaranteed to be UTF-8 text. Decode only the particular values an application expects, using an explicit encoding and error policy.

Do not capture a NUL stream into a shell variable or command substitution. Shell variables cannot represent embedded NUL bytes; keep the stream as a pipe or file and parse it with a byte-aware consumer. A pipeline can also hide which process failed if later commands succeed, so production code should propagate and test the producer’s status instead of assuming a valid-looking prefix is a complete snapshot.

Coreutils 9.12 adds a matching import path

env --env0-from=FILE reads NUL-terminated environment entries from a file. The file must be empty or end in NUL; --env0-from=- reads the stream from standard input. Coreutils 9.12 NEWS identifies this as a new env feature. Check env --version on the actual runner before depending on it: an older GNU release or a non-GNU env may not implement the option.

The import behavior depends on whether --ignore-environment (-i) is present:

Invocation mode	How entries are handled
env --env0-from=FILE command on Unix-like builds	NAME=value replaces the first inherited occurrence of that name; later inherited duplicates remain. Repeated file assignments replace that same slot, so the last file value wins. Entries without = (including empty records) are appended. The native-Windows implementation rejects records without =.
env -i --env0-from=FILE command	The file’s entries replace the inherited environment directly, preserving order and contents, including duplicate names, empty entries, and entries without =.

With -i, this pairing can round-trip the output of env -0. A controlled fixture can stream directly from one invocation to the next without a persistent file:

value=$(printf 'line one\nline two=tail')

env -i --env0-from=/dev/null \
    PATH="$PATH" APP_MODE=fixture "APP_VALUE=$value" \
    env -0 |
env -i --env0-from=- -- python3 -c '
import os

assert os.environ["APP_MODE"] == "fixture"
assert os.environ["APP_VALUE"] == "line one\nline two=tail"
print("controlled environment replay passed")
'

The first env constructs a minimal fixture, then its child GNU env -0 serializes that process environment. The second env clears its own inherited environment and imports the NUL stream before launching Python. PATH is included so the second env can locate python3; substitute the paths and executable names supported by the target image. This example assumes GNU Coreutils 9.12 or newer on a GNU/Linux-style system. /dev/null, GNU option spellings, and the location of Python are platform dependencies, not POSIX shell guarantees.

“Exact” here means the environment entries, not the whole process or machine state. The stream does not restore the current directory, open descriptors, umask, user or group identity, resource limits, namespaces, filesystem contents, or interpreter and utility versions. An unexported shell variable was never part of the environment stream. For reproducible tests, define those other inputs separately instead of treating --env0-from as a process checkpoint.

Treat a snapshot as sensitive input

An environment snapshot is plain data, not an encrypted credential container. It may contain access tokens, cloud credentials, proxy passwords, temporary job credentials, private endpoints, and variables injected by a runner. NUL framing solves record ambiguity; it does not reduce the sensitivity of the values. Prefer constructing a minimal environment with env -i and explicit assignments for tests. If a snapshot must be written, create it in a protected location with restrictive permissions, limit its lifetime, and exclude it from logs and artifact uploads unless the data owner has explicitly approved that handling.

Do not replay a snapshot from an untrusted source into a privileged command. --env0-from is an input parser, not a validation policy. Entries can replace variables that influence executable lookup, library loading, locale, configuration, or application behavior. Review the full record set, enforce an allowlist where the workflow requires one, and supply a known PATH before launching a command. When using Coreutils 9.12’s exact mode, unusual or duplicate entries are preserved by design; that is useful for compatibility tests, but it is not a reason to accept an arbitrary environment file.

Make the format part of the interface contract

Use env -0 when a tool needs an unambiguous machine-readable stream of complete environment entries and the consumer understands NUL-delimited bytes. Use --env0-from when a controlled test needs to reproduce those entries for another process. Keep records byte-oriented, split at the first equals sign, and check that a nonempty stream ends in NUL before treating it as complete.

For ordinary diagnostics, prefer an explicit allowlist and redact values rather than printing everything. For portable scripts, do not assume --null or --env0-from exists just because a command is named env; feature-detect the GNU Coreutils implementation and version or use a small program with a defined binary protocol. The important distinction is that NUL gives the stream a reliable boundary, while environment selection, validation, secrecy, and replay authorization remain separate responsibilities.

Related:

• env in Shell Scripts: Construct a Child Environment Deliberately
• Bash read Delimiters: Safe Lines, NUL-Delimited Paths, and EOF

Sources:

• GNU Coreutils 9.12 manual source: env invocation, --null, and --env0-from
• GNU Coreutils 9.12 env.c: NUL output and environment-file handling
• GNU Coreutils 9.12 release notes: --env0-from introduction and env -0 binary output