# env

_Peios / Using Peios / Peiosutils / Output and evaluation_

> Run a command with a modified environment, or print the current environment.

`env` runs a command with a changed **environment** — the set of `NAME=VALUE` variables a process inherits. Run with no command, it prints the current environment instead.

```
env [options] [NAME=VALUE]... [command [arg]...]
```

```
$ env LANG=C TZ=UTC my-program
$ env
PATH=/bin
HOME=/home/jack
...
```

## How it works

You give `env` a list of `NAME=VALUE` assignments, then a command. `env` applies the assignments to its own environment and then runs the command, which inherits the result. The assignments affect only that one run — your shell's environment is untouched.

This is the clean way to run something with a particular variable set, without changing it for everything else, and the standard way to run a command with one variable temporarily different.

With **no command**, `env` simply prints the environment it would have used — which, with no options, is the current one.

## Building the environment

| Option | Effect |
|---|---|
| `-i`, `--ignore-environment` | Start from an *empty* environment, not the inherited one — so the command sees only what you assign. A bare `-` argument means the same. |
| `-u`, `--unset=NAME` | Remove `NAME` from the environment. |
| `--file=FILE` | Read `NAME=VALUE` lines from a `.env`-style `FILE` and apply them. |

The order is: start (inherited, or empty with `-i`), apply `--file`, apply `--unset`, apply the `NAME=VALUE` arguments.

## Running the command

| Option | Effect |
|---|---|
| `-C`, `--chdir=DIR` | Change to `DIR` before running the command. |
| `--argv0=NAME` | Run the command but present `NAME` as its zeroth argument. |
| `-S`, `--split-string=S` | Split `S` into separate arguments. This exists for script interpreter lines, where everything after the interpreter arrives as one string. |

## Signal handling

`env` can adjust how the command treats signals before launching it:

| Option | Effect |
|---|---|
| `--ignore-signal[=SIG]` | Set the named signals to be ignored. |
| `--default-signal[=SIG]` | Reset the named signals to their default handling. |
| `--block-signal[=SIG]` | Block delivery of the named signals while the command runs. |
| `--list-signal-handling` | List the signal-handling changes the other options requested. |

## Other options

| Option | Effect |
|---|---|
| `-0`, `--null` | When printing the environment, end each line with a NUL character instead of a newline. Not valid together with a command. |
| `-v`, `--debug` | Print each processing step `env` performs. |

## Exit status

When `env` runs a command, it exits with **that command's** status. The exception is a failure in `env` itself:

| Code | Meaning |
|---|---|
| (command's own) | The command ran; this is its exit status. |
| `125` | `env` itself failed — for example, a bad option. |
| `126` | The command was found but could not be run. |
| `127` | The command was not found. |

Related content:

- [printenv](/peios/using-peios/peiosutils/output-and-evaluation/printenv.md)
- [Output and evaluation](/peios/using-peios/peiosutils/output-and-evaluation/overview.md)