> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Bun automatically loads .env files and provides idiomatic ways to read and write environment variables in your project.

Bun reads your `.env` files automatically and provides idiomatic ways to read and write environment variables programmatically. You no longer need packages like `dotenv` or `dotenv-expand`.

## Setting environment variables

### .env files

Bun reads the following files automatically, listed in order of increasing precedence:

1. `.env`
2. `.env.production`, `.env.development`, or `.env.test` (based on the value of `NODE_ENV`)
3. `.env.local`

Variables defined in files with higher precedence override those in files with lower precedence.

```ini .env theme={null}
FOO=hello
BAR=world
```

### Command line

<CodeGroup>
  ```bash Linux/macOS theme={null}
  FOO=helloworld bun run dev
  ```

  ```bash Windows (CMD) theme={null}
  set FOO=helloworld && bun run dev
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:FOO="helloworld"; bun run dev
  ```
</CodeGroup>

<Tip>
  For a cross-platform solution, use [Bun Shell](/runtime/shell). The `bun exec` command runs a shell command cross-platform:

  ```bash theme={null}
  bun exec 'FOO=helloworld bun run dev'
  ```

  On Windows, `package.json` scripts called with `bun run` automatically use the Bun shell, making inline env vars cross-platform:

  ```json package.json theme={null}
  {
    "scripts": {
      "dev": "NODE_ENV=development bun --watch app.ts"
    }
  }
  ```
</Tip>

### Programmatically

Assign directly to `process.env` at runtime:

```typescript theme={null}
process.env.FOO = "hello";
```

***

## Specifying .env files

Use `--env-file` to load a specific `.env` file instead of the defaults. You can pass multiple `--env-file` flags; later files take higher precedence.

```bash theme={null}
# Load a single custom env file
bun --env-file=.env.staging src/index.ts

# Load multiple env files
bun --env-file=.env.base --env-file=.env.override run build
```

### Disabling automatic .env loading

Use `--no-env-file` to skip automatic `.env` loading entirely. This is useful in production or CI environments where environment variables are injected by the platform.

```bash theme={null}
bun run --no-env-file index.ts
```

You can also disable it in `bunfig.toml`:

```toml bunfig.toml theme={null}
# Disable loading .env files
env = false
```

<Note>
  Explicitly provided `--env-file` flags still load their files even when `--no-env-file` or `env = false` is set.
</Note>

***

## Reading environment variables

Access the current environment via `process.env`, `Bun.env`, or `import.meta.env`. All three are equivalent.

```typescript theme={null}
process.env.API_TOKEN;       // => "secret"
Bun.env.API_TOKEN;           // => "secret"
import.meta.env.API_TOKEN;   // => "secret"
```

To print all currently-set environment variables for debugging:

```bash theme={null}
bun --print process.env
```

***

## .env file syntax

### Quotation marks

Bun supports double quotes, single quotes, and backtick template literals:

```ini .env theme={null}
FOO='single quoted'
BAR="double quoted"
BAZ=`backtick quoted`
```

### Variable expansion

Environment variables are automatically expanded. You can reference previously-defined variables in later declarations:

```ini .env theme={null}
FOO=world
BAR=hello$FOO
```

```typescript theme={null}
process.env.BAR; // => "helloworld"
```

This is useful for constructing connection strings:

```ini .env theme={null}
DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/mydb
```

To disable expansion for a specific variable, escape the `$` with a backslash:

```ini .env theme={null}
FOO=world
BAR=hello\$FOO
```

```typescript theme={null}
process.env.BAR; // => "hello$FOO"
```

***

## TypeScript

All `process.env` properties are typed as `string | undefined` by default:

```typescript theme={null}
Bun.env.SOME_VAR; // string | undefined
```

To add autocompletion and tell TypeScript to treat a variable as a non-optional string, use interface merging. Add the following declaration to any file in your project:

```typescript theme={null}
declare module "bun" {
  interface Env {
    MY_REQUIRED_VAR: string;
  }
}
```

Now `process.env.MY_REQUIRED_VAR` and `Bun.env.MY_REQUIRED_VAR` are typed as `string` (not `string | undefined`).

***

## Bun-specific environment variables

These environment variables configure aspects of Bun's own behavior:

| Variable                                 | Description                                                                                                                             |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_TLS_REJECT_UNAUTHORIZED`           | Set to `0` to disable SSL certificate validation. Use for testing only.                                                                 |
| `BUN_CONFIG_VERBOSE_FETCH`               | Set to `curl` to log fetch request/response headers. Set to `1` for the same output without curl formatting.                            |
| `BUN_RUNTIME_TRANSPILER_CACHE_PATH`      | Directory for the runtime transpiler cache. Set to `0` or empty string to disable caching.                                              |
| `TMPDIR`                                 | Directory for temporary files during bundling. Defaults to `/tmp` (Linux) or `/private/tmp` (macOS).                                    |
| `NO_COLOR`                               | Set to `1` to disable ANSI color output.                                                                                                |
| `FORCE_COLOR`                            | Set to `1` to force ANSI color output even when `NO_COLOR` is set.                                                                      |
| `BUN_CONFIG_MAX_HTTP_REQUESTS`           | Maximum concurrent HTTP requests for `fetch` and `bun install`. Defaults to `256`.                                                      |
| `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD` | Set to `true` to prevent `bun --watch` from clearing the terminal on reload.                                                            |
| `DO_NOT_TRACK`                           | Set to `1` to disable crash report uploads and telemetry.                                                                               |
| `BUN_OPTIONS`                            | Prepends CLI arguments to every Bun invocation. For example, `BUN_OPTIONS="--hot"` makes `bun run dev` behave like `bun --hot run dev`. |

***

## Runtime transpiler cache

For files larger than 50 KB, Bun caches transpiled output to speed up subsequent runs. The cache is global, content-addressable, and safe to delete at any time.

<Note>
  It is recommended to disable the transpiler cache when using ephemeral filesystems like Docker. Bun's official Docker images disable this cache automatically.
</Note>

To disable the cache:

```bash theme={null}
BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
```