bun.sh/docs/runtime/env.md

Bun reads your .env files automatically and provides idiomatic ways to read and write your environment variables programmatically. Plus, some aspects of Bun's runtime behavior can be configured with Bun-specific environment variables.

Setting environment variables

Bun reads the following files automatically (listed in order of increasing precedence).

• .env
• .env.production, .env.development, .env.test (depending on value of NODE_ENV)
• .env.local

FOO=hello
BAR=world

Variables can also be set via the command line.

$ FOO=helloworld bun run dev

Or programmatically by assigning a property to process.env.

process.env.FOO = "hello";

Manually specifying .env files

Bun supports --env-file to override which specific .env file to load. You can use --env-file when running scripts in bun's runtime, or when running package.json scripts.

bun --env-file=.env.1 src/index.ts

bun --env-file=.env.abc --env-file=.env.def run build

Quotation marks

Bun supports double quotes, single quotes, and

Expansion

Environment variables are automatically expanded. This means you can reference previously-defined variables in your environment variables.

FOO=world
BAR=hello$FOO

process.env.BAR; // => "helloworld"

This is useful for constructing connection strings or other compound values.

DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME

This can be disabled by escaping the $ with a backslash.

FOO=world
BAR=hello\$FOO

process.env.BAR; // => "hello$FOO"

dotenv

Generally speaking, you won't need dotenv or dotenv-expand anymore, because Bun reads .env files automatically.

Reading environment variables

The current environment variables can be accessed via process.env.

process.env.API_TOKEN; // => "secret"

Bun also exposes these variables via Bun.env and import.meta.env, which is a simple alias of process.env.

Bun.env.API_TOKEN; // => "secret"
import.meta.env.API_TOKEN; // => "secret"

To print all currently-set environment variables to the command line, run bun run env. This is useful for debugging.

$ bun run env
BAZ=stuff
FOOBAR=aaaaaa
<lots more lines>

TypeScript

In TypeScript, all properties of process.env are typed as string | undefined.

Bun.env.whatever;
// string | undefined

To get autocompletion and tell TypeScript to treat a variable as a non-optional string, we'll use interface merging.

declare module "bun" {
  interface Env {
    AWESOME: string;
  }
}

Add this line to any file in your project. It will globally add the AWESOME property to process.env and Bun.env.

process.env.AWESOME; // => string

Configuring Bun

These environment variables are read by Bun and configure aspects of its behavior.

{% table %}

• Name
• Description

---

• TMPDIR
• Bun occasionally requires a directory to store intermediate assets during bundling or other operations. If unset, defaults to the platform-specific temporary directory: /tmp on Linux, /private/tmp on macOS.

---

• NO_COLOR
• If NO_COLOR=1, then ANSI color output is disabled.

---

• FORCE_COLOR
• If FORCE_COLOR=1, then ANSI color output is force enabled, even if NO_COLOR is set.

---

• DO_NOT_TRACK
• If DO_NOT_TRACK=1, then analytics are disabled. Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it's not a lot of data. Equivalent of telemetry=false in bunfig.

{% /table %}