bunfig.toml

bunfig.toml is Bun's configuration file.

Bun relies on pre-existing configuration files like package.json and tsconfig.json where it can; bunfig.toml is only for Bun-specific settings. The file is optional, and Bun works without it.

Global vs. local#

Put bunfig.toml in your project root, alongside your package.json.

To configure Bun's package manager globally, you can also create a .bunfig.toml file at one of the following paths:

• $HOME/.bunfig.toml
• $XDG_CONFIG_HOME/.bunfig.toml

Only package manager commands (bun install, bun add, bun remove, bun update, bun pm, bunx, and so on) read the global file. If Bun finds both a global and a local bunfig, it loads both; keys set in the local file override the same keys in the global file. CLI flags override bunfig settings where applicable.

Runtime#

Top-level fields in bunfig.toml configure Bun's runtime behavior.

preload#

An array of scripts/plugins to execute before running a file or script.

# scripts to run before `bun run`-ing a file or script
# register plugins by adding them to this list
preload = ["./preload.ts"]

jsx#

Configure how Bun handles JSX. You can also set these fields in the compilerOptions of your tsconfig.json, but bunfig.toml supports them for non-TypeScript projects.

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

Refer to the tsconfig docs for more information on these fields.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol#

Enable smol mode. This reduces memory usage at the cost of performance.

# Reduce memory usage at the cost of performance
smol = true

logLevel#

Set the log level: "debug", "warn", or "error".

logLevel = "debug" # "debug" | "warn" | "error"

define#

The define field replaces global identifiers with constant expressions wherever they appear. The expression should be a JSON string.

[define]
# Replace any usage of "process.env.bagel" with the string `lox`.
# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
"process.env.bagel" = "'lox'"

loader#

Configure how Bun maps file extensions to loaders. Use this to load file types Bun doesn't support natively.

[loader]
# when a .bagel file is imported, treat it like a tsx file
".bagel" = "tsx"

Bun supports the following loaders:

• jsx
• js
• ts
• tsx
• css
• file
• json
• toml
• wasm
• napi
• base64
• dataurl
• text

telemetry#

The telemetry field enables or disables analytics. By default, telemetry is enabled. This setting is equivalent to the DO_NOT_TRACK environment variable.

We do not currently collect telemetry; this setting only controls anonymous crash reports. We plan to collect information like which Bun APIs are used most or how long bun build takes.

telemetry = false

env#

Configure automatic .env file loading. Bun loads .env files by default. To disable this behavior:

# Disable automatic .env file loading
env = false

You can also use object syntax with the file property:

[env]
file = false

Use this in production or CI/CD pipelines where you want to rely solely on system environment variables.

Bun still loads files passed explicitly with --env-file even when default loading is disabled.

console#

Configure console output behavior.

console.depth#

Set the default depth for console.log() object inspection. Default 2.

[console]
depth = 3

Higher values show more nested properties but may produce verbose output for complex objects. The --console-depth CLI flag overrides this setting.

Serve#

The [serve] section configures Bun.serve and bun run when serving HTTP.

serve.port#

The default port for Bun.serve to listen on. Default 3000. You can also set it with the BUN_PORT or PORT environment variables, or the --port flag.

[serve]
port = 3000

Test runner#

The [test] section of bunfig.toml configures the test runner.

[test]
# configuration goes here

test.root#

The root directory to run tests from. Default ..

[test]
root = "./__tests__"

test.preload#

Same as the top-level preload field, but only applies to bun test.

[test]
preload = ["./setup.ts"]

test.pathIgnorePatterns#

Exclude files and directories from test discovery using glob patterns. The test runner prunes matched directories during scanning, so it never traverses their contents. Use this when your project contains submodules or vendored code with *.test.ts files that you don't want bun test to pick up.

[test]
pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"]

Equivalent CLI flag: --path-ignore-patterns. CLI flags override the bunfig.toml value entirely.

test.smol#

Same as the top-level smol field, but only applies to bun test.

[test]
smol = true

test.coverage#

Enables coverage reporting. Default false. Use --coverage to override.

[test]
coverage = false

test.coverageThreshold#

The coverage threshold. By default, no threshold is set. If your test suite does not meet it, bun test exits with a non-zero exit code.

[test]

# to require 90% line-level and function-level coverage
coverageThreshold = 0.9

You can set separate thresholds for line and function coverage. Bun accepts a statements key but does not currently enforce it.

[test]
coverageThreshold = { lines = 0.7, functions = 0.8 }

test.coverageSkipTestFiles#

Whether to skip test files when computing coverage statistics. Default false.

[test]
coverageSkipTestFiles = false

test.coverageIgnoreSourcemaps#

Whether to report coverage against transpiled output instead of remapping line numbers through sourcemaps back to the original source. Default false. Primarily useful for debugging.

[test]
coverageIgnoreSourcemaps = false

test.coveragePathIgnorePatterns#

Exclude files from coverage reports using glob patterns. Accepts a single pattern or an array of patterns.

[test]
# Single pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Multiple patterns
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter#

By default, the test runner prints coverage reports to the console. For persistent reports that CI and other tools can read, use lcov.

[test]
coverageReporter  = ["text", "lcov"]  # default ["text"]

test.coverageDir#

Set the path where coverage reports are saved. This only applies to persistent reporters like lcov.

[test]
coverageDir = "path/to/somewhere"  # default "coverage"

test.randomize#

Run tests in random order. Default false.

[test]
randomize = true

Running tests in a different order each time helps catch bugs related to test interdependencies. When combined with seed, the random order becomes reproducible.

The --randomize CLI flag overrides this setting.

test.seed#

Set the random seed for test randomization. This option requires randomize to be true.

[test]
randomize = true
seed = 2444615283

A seed makes the randomized test order reproducible across runs, which helps when debugging flaky tests.

The --seed CLI flag overrides this setting.

test.rerunEach#

Re-run each test file a specified number of times. Default 0 (run once).

[test]
rerunEach = 3

Use this to catch flaky tests or non-deterministic behavior.

The --rerun-each CLI flag overrides this setting.

test.retry#

Default retry count for all tests. The test runner retries failed tests up to this many times. Per-test { retry: N } overrides this value. Default 0 (no retries).

[test]
retry = 3

The --retry CLI flag overrides this setting.

test.concurrentTestGlob#

Test files matching this glob pattern run all of their tests concurrently, as if you passed the --concurrent flag.

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"

Use this to migrate a test suite to concurrent execution gradually, or to run integration tests concurrently while keeping unit tests sequential.

The --concurrent CLI flag overrides this setting.

test.onlyFailures#

When enabled, the output shows only failed tests, which reduces noise in large test suites. Default false.

[test]
onlyFailures = true

Equivalent to the --only-failures flag.

test.reporter#

Configure the test reporter settings.

test.reporter.dots#

Enable the dots reporter, which prints one dot per test. Default false.

[test.reporter]
dots = true

test.reporter.junit#

Enable JUnit XML reporting and specify the output file path.

[test.reporter]
junit = "test-results.xml"

CI systems and other tools can consume the report.

Package manager#

The [install] section configures the behavior of bun install.

[install]
# configuration here

install.optional#

Whether to install optional dependencies. Default true.

[install]
optional = true

install.dev#

Whether to install development dependencies. Default true.

[install]
dev = true

install.peer#

Whether to install peer dependencies. Default true.

[install]
peer = true

install.production#

Whether bun install runs in "production mode". Default false.

In production mode, Bun does not install "devDependencies" and freezes the lockfile (same as install.frozenLockfile). Use the --production CLI flag to enable it for a single install. Since production mode freezes the lockfile, bun add, bun remove, and bun update fail while it is set.

[install]
production = false

install.exact#

Whether to set an exact version in package.json. Default false.

By default Bun uses caret ranges. If the latest version of a package is 2.4.1, Bun writes ^2.4.1 to your package.json. That range accepts any version from 2.4.1 up to (but not including) 3.0.0.

[install]
exact = false

install.ignoreScripts#

Whether to skip lifecycle scripts during install. Default false. Equivalent to the --ignore-scripts flag.

When true, Bun does not run any preinstall / install / postinstall / prepare scripts, both for your project and for packages in trustedDependencies. See Lifecycle scripts.

[install]
ignoreScripts = false

install.concurrentScripts#

The maximum number of concurrent lifecycle scripts to run at once. Defaults to two times the number of CPU cores. Equivalent to the --concurrent-scripts flag.

[install]
concurrentScripts = 5

install.saveTextLockfile#

If false, bun install generates a binary bun.lockb instead of a text-based bun.lock file when no lockfile is present.

Default true (since Bun v1.2).

[install]
saveTextLockfile = false

install.auto#

Configure Bun's auto-install behavior. Default "auto" — when no node_modules folder is found, Bun installs dependencies on the fly during execution.

[install]
auto = "auto"

Valid values are:

install.prefer#

Configure how Bun resolves package versions against the npm registry when running scripts. Default "online".

[install]
prefer = "online"

Valid values are:

install.frozenLockfile#

When true, bun install does not update bun.lock. Default false. If package.json and the existing bun.lock disagree, the install errors.

[install]
frozenLockfile = false

install.dryRun#

Whether bun install resolves dependencies without installing them. Default false. When true, it's equivalent to passing --dry-run to all bun install commands.

[install]
dryRun = false

install.globalDir#

The directory where Bun puts globally installed packages.

Environment variable: BUN_INSTALL_GLOBAL_DIR

[install]
# where `bun install --global` installs packages
globalDir = "~/.bun/install/global"

install.globalBinDir#

The directory where Bun links the binaries of globally installed packages.

Environment variable: BUN_INSTALL_BIN

[install]
# where globally-installed package bins are linked
globalBinDir = "~/.bun/bin"

install.registry#

The default registry is https://registry.npmjs.org/. To change it:

[install]
# set default registry as a string
registry = "https://registry.npmjs.org"
# set a token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# set a username/password
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages#

Whether to link workspace packages from the monorepo root to their respective node_modules directories. Default true.

[install]
linkWorkspacePackages = true

install.scopes#

To configure a registry for a particular scope (for example, @myorg/<package>), use install.scopes. You can reference environment variables with $variable notation.

[install.scopes]
# registry as string
myorg = "https://username:password@registry.myorg.com/"

# registry with username/password
# you can reference environment variables
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# registry with token
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

install.ca and install.cafile#

To configure a CA certificate, set install.ca to the certificate string or install.cafile to the path of a certificate file.

[install]
# The CA certificate as a string
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# A path to a CA certificate file. The file can contain multiple certificates.
cafile = "path/to/cafile"

install.cache#

To configure the cache behavior:

[install.cache]

# the directory to use for the cache
dir = "~/.bun/install/cache"

# when true, don't load from the global cache.
# Bun may still write to node_modules/.cache
disable = false

# when true, always resolve the latest versions from the registry
disableManifest = false

install.lockfile#

Whether to generate a lockfile on bun install. Default true.

[install.lockfile]
save = true

Whether to generate a non-Bun lockfile alongside bun.lock. (Bun always creates a bun.lock.) "yarn" is the only supported value.

[install.lockfile]
print = "yarn"

install.linker#

Configure the linker strategy: how bun install lays out dependencies in node_modules. Defaults to "isolated" for new workspaces, "hoisted" for new single-package projects and existing projects (made pre-v1.3.2).

See Isolated installs.

[install]
linker = "hoisted"

Valid values are:

install.globalStore#

When using the "isolated" linker, share package installations across projects in a global virtual store at <cache>/links/. Bun links node_modules/.bun/<pkg>@<ver> into the store instead of materializing each package into the project. Makes warm installs after rm -rf node_modules an order of magnitude faster. Default false. You can also set it with the BUN_INSTALL_GLOBAL_STORE environment variable.

See Global virtual store.

[install]
globalStore = true

install.publicHoistPattern#

When using the "isolated" linker, Bun hoists packages matching these glob patterns to the root node_modules directory so any package in the project can resolve them. Default []. Similar to pnpm's public-hoist-pattern.

[install]
publicHoistPattern = ["*eslint*", "*prettier*"]

install.hoistPattern#

When using the "isolated" linker, Bun hoists packages matching these glob patterns to a fallback directory inside the virtual store (node_modules/.bun/node_modules) so other packages in the virtual store can resolve them. By default Bun hoists every package there, equivalent to ["*"]. Similar to pnpm's hoist-pattern.

[install]
hoistPattern = ["*"]

install.hoist#

When using the "isolated" linker, Bun creates node_modules/.bun/node_modules. This fallback directory contains a symlink to every installed package, or only to the packages matching install.hoistPattern when one is set. The directory sits on the upward resolution path of every package in the store, so a package can still resolve dependencies it never declared ("phantom dependencies"). Set hoist = false to skip creating this directory entirely. An undeclared import from a store package then fails unless the imported package is linked at the project root node_modules (a direct dependency, a publicHoistPattern match, or a workspace package). The root node_modules stays on the resolution path because .bun lives inside it. The project's own node_modules symlinks are unchanged. Default true. Equivalent to pnpm's hoist setting, including this root-node_modules caveat; takes precedence over install.hoistPattern.

This setting only applies to the "isolated" linker. Hoisted installs are unaffected: there the flat node_modules tree is the layout itself, not something this switch controls.

[install]
hoist = false

install.logLevel#

Set the log level for bun install. This can be one of "debug", "warn", or "error".

[install]
logLevel = "warn"

install.security.scanner#

Configure a security scanner to scan packages for vulnerabilities before installation.

First, install a security scanner from npm:

bun add -d @oven/bun-security-scanner

Then configure it in your bunfig.toml:

[install.security]
scanner = "@oven/bun-security-scanner" # example name, replace with your scanner's package

When a security scanner is configured:

• Auto-install is automatically disabled for security
• Packages are scanned before installation
• Installation is cancelled if fatal issues are found
• Security warnings are displayed during installation

Learn more about using and writing security scanners.

install.minimumReleaseAge#

Configure a minimum age (in seconds) for npm package versions. During installation, Bun filters out package versions published more recently than this threshold. Default null (disabled).

[install]
# Only install package versions published at least 3 days ago
minimumReleaseAge = 259200

See Minimum release age.

install.minimumReleaseAgeExcludes#

An array of package names that are exempt from the minimumReleaseAge check. Default [].

[install]
minimumReleaseAge = 259200
# These packages will bypass the 3-day minimum age requirement
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

bun run#

The [run] section configures the bun run command. These settings also apply to the bun command when running a file, script, or executable.

For bun run, Bun only loads the local project's bunfig.toml automatically (it doesn't check for a global .bunfig.toml).

run.shell - use the system shell or Bun's shell#

The shell used to run package.json scripts with bun run or bun. Defaults to "bun" on Windows and "system" on other platforms.

To always use the system shell instead of Bun's shell (the default everywhere except Windows):

[run]
# default outside of Windows
shell = "system"

To always use Bun's shell instead of the system shell:

[run]
# default on Windows
shell = "bun"

run.bun - auto alias node to bun#

When true, Bun prepends $PATH with a node symlink that points to the bun binary for all scripts or executables invoked by bun run or bun.

A script that runs node runs bun instead, with no changes to the script. This works recursively, so a script that runs another script that runs node also runs bun. The alias also applies to shebangs that point to node.

By default, this is enabled if node is not already in your $PATH.

[run]
# equivalent to `bun --bun` for all `bun run` commands
bun = true

You can test this by running:

bun --bun which node # /path/to/bun
bun which node # /path/to/node

This option is equivalent to prefixing all bun run commands with --bun:

bun --bun run dev
bun --bun dev
bun run --bun dev

Set to false to disable the node symlink.

run.silent - suppress reporting the command being run#

When true, bun run and bun don't print the command being run.

[run]
silent = true

Without this option, Bun prints the command being run to the console:

bun run dev
echo "Running \"dev\"..."

Running "dev"...

With this option, Bun does not print the command being run:

bun run dev

Running "dev"...

This is equivalent to passing --silent to all bun run commands:

bun --silent run dev
bun --silent dev
bun run --silent dev

run.elide-lines - truncate filtered output#

The number of lines of script output shown per script when using --filter. Default 10. Set to 0 to show all lines. Equivalent to the --elide-lines flag.

[run]
elide-lines = 10

run.noOrphans - don't leave orphan processes behind#

When true, Bun watches the process that spawned it and exits as soon as that parent goes away, even if the parent was force-killed and never got a chance to forward a signal. On its own exit, Bun also terminates every descendant process so nothing it spawned outlives it. Useful when Bun is launched by a supervisor (Electron, a CI runner, a thin shim) that may be force-killed.

On Linux, Bun uses prctl(PR_SET_PDEATHSIG) and a /proc descendant walk. On macOS, it uses EVFILT_PROC/NOTE_EXIT on the event loop's kqueue and a libproc descendant walk. On Windows, it uses a thread-pool wait on the parent's process handle and a kill-on-close Job Object.

Equivalent to the --no-orphans CLI flag or the BUN_FEATURE_FLAG_NO_ORPHANS=1 environment variable.

[run]
noOrphans = true