bun --env-file: choose which .env file Bun loads

Bun reads .env files automatically: without any flag, bun index.ts loads .env, .env.$NODE_ENV (.env.development by default) and .env.local from the current directory into process.env and Bun.env. bun --env-file=.env.staging index.ts loads the named file instead, which is how you pick the configuration for one environment. Variables already set in the shell win over every file.

Automatic loading and --env-file

cat > .env <<'EOF'
PORT=8080
NAME=default
EOF
cat > .env.staging <<'EOF'
PORT=7000
EOF
cat > main.ts <<'EOF'
console.log("PORT =", process.env.PORT, "| NAME =", process.env.NAME);
EOF
echo "--- bun main.ts (automatic .env)"
npx --yes bun@1 main.ts
echo "--- bun --env-file=.env.staging main.ts"
npx --yes bun@1 --env-file=.env.staging main.ts
echo "--- shell variable wins"
PORT=9000 npx --yes bun@1 --env-file=.env.staging main.ts

--- bun main.ts (automatic .env)
PORT = 8080 | NAME = default
--- bun --env-file=.env.staging main.ts
PORT = 7000 | NAME = undefined
--- shell variable wins
PORT = 9000 | NAME = undefined

NAME exists only in .env. It is set in the first run and undefined with --env-file=.env.staging: the named file replaces the automatic list instead of adding to it. The shell value of PORT beats the file.

Load order without the flag

Later files override earlier ones, so .env.local can hold developer-specific values on top of the committed .env.

Syntax extras

Bun's parser supports variable expansion, which Node.js does not:

# .env
HOST=db.local
DATABASE_URL=postgres://${HOST}/app   # becomes postgres://db.local/app in Bun
LITERAL=\$NOT_EXPANDED                # a backslash keeps the dollar sign

Quotes around values are removed, and # starts a comment on unquoted lines. Every value is a string.

Pitfalls

• Because loading is automatic, a forgotten .env in the working directory changes behaviour without any flag on the command line. Check process.env when a value looks wrong.
• The flag goes before the script or file: bun main.ts --env-file=x passes the text to your program.
• bun build does not inline these variables unless you configure env in the build options; runtime and bundling are separate.
• Keep credentials in .env.local (git-ignored) and commit only placeholder values.

Node.js and Deno have explicit flags with similar rules: node --env-file and deno run --env-file.

FAQ