bunfig.toml

Bun’s behavior can be configured using its configuration file, bunfig.toml. In general, Bun relies on pre-existing configuration files like package.json and tsconfig.json to configure its behavior. bunfig.toml is only necessary for configuring Bun-specific things. This file is optional, and Bun will work out of the box without it.

Global vs. local

In general, it’s recommended to add a bunfig.toml file to your project root, alongside your package.json. To configure Bun globally, you can also create a .bunfig.toml file at one of the following paths:

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

If both a global and local bunfig are detected, the results are shallow-merged, with local overriding global. CLI flags will override bunfig setting where applicable.

Runtime

Bun’s runtime behavior is configured using top-level fields in the bunfig.toml file.

`preload`

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

bunfig.toml

# 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 they are supported here as well for non-TypeScript projects.

bunfig.toml

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

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

`smol`

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

bunfig.toml

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

`logLevel`

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

bunfig.toml

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

`define`

The define field allows you to replace certain global identifiers with constant expressions. Bun will replace any usage of the identifier with the expression. The expression should be a JSON string.

bunfig.toml

[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. This is useful for loading files that aren’t natively supported by Bun.

bunfig.toml

[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 is used to enable/disable analytics. By default, telemetry is enabled. This is equivalent to the DO_NOT_TRACK environment variable. Currently we do not collect telemetry and this setting is only used for enabling/disabling anonymous crash reports, but in the future we plan to collect information like which Bun APIs are used most or how long bun build takes.

bunfig.toml

telemetry = false

`env`

Configure automatic .env file loading. By default, Bun automatically loads .env files. To disable this behavior:

bunfig.toml

# Disable automatic .env file loading
env = false

You can also use object syntax with the file property:

bunfig.toml

[env]
file = false

This is useful in production environments or CI/CD pipelines where you want to rely solely on system environment variables. Note: Explicitly provided environment files via --env-file will still be loaded even when default loading is disabled.

`console`

Configure console output behavior.

`console.depth`

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

bunfig.toml

[console]
depth = 3

This controls how deeply nested objects are displayed in console output. Higher values show more nested properties but may produce verbose output for complex objects. This setting can be overridden by the --console-depth CLI flag.

Serve

Options for Bun.serve and bun run when serving HTTP are configured under the [serve] section.

`serve.port`

The default port for Bun.serve to listen on. Default 3000. Can also be set via the BUN_PORT or PORT environment variables, or the --port flag.

bunfig.toml

[serve]
port = 3000

Test runner

The test runner is configured under the [test] section of your bunfig.toml.

bunfig.toml

[test]
# configuration goes here

`test.root`

The root directory to run tests from. Default ..

bunfig.toml

[test]
root = "./__tests__"

`test.preload`

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

bunfig.toml

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

`test.pathIgnorePatterns`

Exclude files and directories from test discovery using glob patterns. Matched directories are pruned during scanning, so their contents are never traversed. This is useful when your project contains submodules or vendored code with *.test.ts files that you don’t want bun test to pick up.

bunfig.toml

[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.

bunfig.toml

[test]
smol = true

`test.coverage`

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

bunfig.toml

[test]
coverage = false

`test.coverageThreshold`

To specify a coverage threshold. By default, no threshold is set. If your test suite does not meet or exceed this threshold, bun test will exit with a non-zero exit code to indicate the failure.

bunfig.toml

[test]

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

Different thresholds can be specified for line-wise, function-wise, and statement-wise coverage.

bunfig.toml

[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

`test.coverageSkipTestFiles`

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

bunfig.toml

[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.

bunfig.toml

[test]
coverageIgnoreSourcemaps = false

`test.coveragePathIgnorePatterns`

Exclude specific files or file patterns from coverage reports using glob patterns. Can be a single string pattern or an array of patterns.

bunfig.toml

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

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

`test.coverageReporter`

By default, coverage reports will be printed to the console. For persistent code coverage reports in CI environments and for other tools use lcov.

bunfig.toml

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

`test.coverageDir`

Set path where coverage reports will be saved. Please notice, that it works only for persistent coverageReporter like lcov.

bunfig.toml

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

`test.randomize`

Run tests in random order. Default false.

bunfig.toml

[test]
randomize = true

This helps catch bugs related to test interdependencies by running tests in a different order each time. When combined with seed, the random order becomes reproducible. The --randomize CLI flag will override this setting when specified.

`test.seed`

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

bunfig.toml

[test]
randomize = true
seed = 2444615283

Using a seed makes the randomized test order reproducible across runs, which is useful for debugging flaky tests. When you encounter a test failure with randomization enabled, you can use the same seed to reproduce the exact test order. The --seed CLI flag will override this setting when specified.

`test.rerunEach`

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

bunfig.toml

[test]
rerunEach = 3

This is useful for catching flaky tests or non-deterministic behavior. Each test file will be executed the specified number of times. The --rerun-each CLI flag will override this setting when specified.

`test.retry`

Default retry count for all tests. Failed tests will be retried up to this many times. Per-test { retry: N } overrides this value. Default 0 (no retries).

bunfig.toml

[test]
retry = 3

The --retry CLI flag will override this setting when specified.

`test.concurrentTestGlob`

Specify a glob pattern to automatically run matching test files with concurrent test execution enabled. Test files matching this pattern will behave as if the --concurrent flag was passed, running all tests within those files concurrently.

bunfig.toml

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

This is useful for:

Gradually migrating test suites to concurrent execution
Running integration tests concurrently while keeping unit tests sequential
Separating fast concurrent tests from tests that require sequential execution

The --concurrent CLI flag will override this setting when specified.

`test.onlyFailures`

When enabled, only failed tests are displayed in the output. This helps reduce noise in large test suites by hiding passing tests. Default false.

bunfig.toml

[test]
onlyFailures = true

This is equivalent to using the --only-failures flag when running bun test.

`test.reporter`

Configure the test reporter settings.

`test.reporter.dots`

Enable the dots reporter, which displays a compact output showing a dot for each test. Default false.

bunfig.toml

[test.reporter]
dots = true

`test.reporter.junit`

Enable JUnit XML reporting and specify the output file path.

bunfig.toml

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

This generates a JUnit XML report that can be consumed by CI systems and other tools.

Package manager

Package management is a complex issue; to support a range of use cases, the behavior of bun install can be configured under the [install] section.

bunfig.toml

[install]
# configuration here

`install.optional`

Whether to install optional dependencies. Default true.

bunfig.toml

[install]
optional = true

`install.dev`

Whether to install development dependencies. Default true.

bunfig.toml

[install]
dev = true

`install.peer`

Whether to install peer dependencies. Default true.

bunfig.toml

[install]
peer = true

`install.production`

Whether bun install will run in “production mode”. Default false. In production mode, "devDependencies" are not installed. You can use --production in the CLI to override this setting.

bunfig.toml

[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, the version range in your package.json will be ^2.4.1. This indicates that any version from 2.4.1 up to (but not including) 3.0.0 is acceptable.

bunfig.toml

[install]
exact = false

`install.ignoreScripts`

Whether to skip lifecycle scripts during install. Default false. Equivalent to the --ignore-scripts flag. When true, Bun will not run any preinstall / install / postinstall / prepare scripts — both for your project and for packages in trustedDependencies. See Lifecycle scripts for more details.

bunfig.toml

[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.

bunfig.toml

[install]
concurrentScripts = 5

`install.saveTextLockfile`

If false, generate a binary bun.lockb instead of a text-based bun.lock file when running bun install and no lockfile is present. Default true (since Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

`install.auto`

To configure Bun’s package auto-install behavior. Default "auto" — when no node_modules folder is found, Bun will automatically install dependencies on the fly during execution.

bunfig.toml

[install]
auto = "auto"

Valid values are:

Value	Description
`"auto"`	Resolve modules from local `node_modules` if it exists. Otherwise, auto-install dependencies on the fly.
`"force"`	Always auto-install dependencies, even if `node_modules` exists.
`"disable"`	Never auto-install dependencies.
`"fallback"`	Check local `node_modules` first, then auto-install any packages that aren’t found. You can enable this from the CLI with `bun -i`.

`install.prefer`

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

bunfig.toml

[install]
prefer = "online"

Valid values are:

Value	Description
`"online"`	Default. Check the registry for stale packages as needed.
`"offline"`	Skip staleness checks and resolve packages from the local cache. Equivalent to `--prefer-offline`.
`"latest"`	Always check npm for the latest matching versions. Equivalent to `--prefer-latest`.

`install.frozenLockfile`

When true, bun install will not update bun.lock. Default false. If package.json and the existing bun.lock are not in agreement, this will error.

bunfig.toml

[install]
frozenLockfile = false

`install.dryRun`

Whether bun install will actually install dependencies. Default false. When true, it’s equivalent to setting --dry-run on all bun install commands.

bunfig.toml

[install]
dryRun = false

`install.globalDir`

To configure the directory where Bun puts globally installed packages. Environment variable: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

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

`install.globalBinDir`

To configure the directory where Bun installs globally installed binaries and CLIs. Environment variable: BUN_INSTALL_BIN

bunfig.toml

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

`install.registry`

The default registry is https://registry.npmjs.org/. This can be globally configured in bunfig.toml:

bunfig.toml

[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`

To configure how workspace packages are linked, use the install.linkWorkspacePackages option. Whether to link workspace packages from the monorepo root to their respective node_modules directories. Default true.

bunfig.toml

[install]
linkWorkspacePackages = true

`install.scopes`

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

bunfig.toml

[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, use install.ca or install.cafile to specify a path to a CA certificate file.

bunfig.toml

[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:

bunfig.toml

[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`

To configure lockfile behavior, use the install.lockfile section. Whether to generate a lockfile on bun install. Default true.

bunfig.toml

[install.lockfile]
save = true

Whether to generate a non-Bun lockfile alongside bun.lock. (A bun.lock will always be created.) Currently "yarn" is the only supported value.

bunfig.toml

[install.lockfile]
print = "yarn"

`install.linker`

Configure the linker strategy for installing dependencies. Defaults to "isolated" for new workspaces, "hoisted" for new single-package projects and existing projects (made pre-v1.3.2). For complete documentation refer to Package manager > Isolated installs.

bunfig.toml

[install]
linker = "hoisted"

Valid values are:

Value	Description
`"hoisted"`	Link dependencies in a shared `node_modules` directory.
`"isolated"`	Link dependencies inside each package installation.

`install.globalStore`

When using the "isolated" linker, share package installations across projects in a global virtual store at <cache>/links/ and link node_modules/.bun/<pkg>@<ver> into it instead of materializing each package into the project. Makes warm installs after rm -rf node_modules an order of magnitude faster. Default false. Can also be set with the BUN_INSTALL_GLOBAL_STORE environment variable. For complete documentation refer to Package manager > Global virtual store.

bunfig.toml

[install]
globalStore = true

`install.publicHoistPattern`

When using the "isolated" linker, packages matching these glob patterns are hoisted to the root node_modules directory so they can be resolved by any package in the project. Default []. Similar to pnpm’s public-hoist-pattern.

bunfig.toml

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

`install.hoistPattern`

When using the "isolated" linker, packages matching these glob patterns are hoisted to the virtual store root (node_modules/.bun) so they can be resolved by other packages in the virtual store. Default []. Similar to pnpm’s hoist-pattern.

bunfig.toml

[install]
hoistPattern = ["*"]

`install.logLevel`

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

bunfig.toml

[install]
logLevel = "warn"

`install.security.scanner`

Configure a security scanner to scan packages for vulnerabilities before installation. First, install a security scanner from npm:

terminal

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

@oven/bun-security-scanner is an example package name, not a real package. Replace it with the scanner you want to use, and consult that scanner’s documentation for the exact package name and installation instructions. Most scanners are installed with bun add.

Then configure it in your bunfig.toml:

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. Package versions published more recently than this threshold will be filtered out during installation. Default is null (disabled).

bunfig.toml

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

For more details see Minimum release age in the install documentation.

`install.minimumReleaseAgeExcludes`

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

bunfig.toml

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

`bun run`

The bun run command can be configured under the [run] section. These apply to the bun run command and the bun command when running a file or executable or script. Currently, bunfig.toml is only automatically loaded for bun run in a local project (it doesn’t check for a global .bunfig.toml).

`run.shell` - use the system shell or Bun’s shell

The shell to use when running package.json scripts via bun run or bun. On Windows, this defaults to "bun" and on other platforms it defaults to "system". To always use the system shell instead of Bun’s shell (default behavior unless Windows):

bunfig.toml

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

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

bunfig.toml

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

`run.bun` - auto alias `node` to `bun`

When true, this prepends $PATH with a node symlink that points to the bun binary for all scripts or executables invoked by bun run or bun. This means that if you have a script that runs node, it will actually run bun instead, without needing to change your script. This works recursively, so if your script runs another script that runs node, it will also run bun instead. This applies to shebangs as well, so if you have a script with a shebang that points to node, it will actually run bun instead. By default, this is enabled if node is not already in your $PATH.

bunfig.toml

[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

If set to false, this will disable the node symlink.

`run.silent` - suppress reporting the command being run

When true, suppresses the output of the command being run by bun run or bun.

bunfig.toml

[run]
silent = true

Without this option, the command being run will be printed to the console:

terminal

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

Running "dev"...

With this option, the command being run will not be printed to the console:

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.

bunfig.toml

[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 SIGKILLed and never got a chance to forward a signal. On its own exit, Bun also recursively SIGKILLs 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. Linux and macOS only (no-op on Windows and other platforms). Equivalent to the --no-orphans CLI flag or the BUN_FEATURE_FLAG_NO_ORPHANS=1 environment variable.

bunfig.toml

[run]
noOrphans = true

​Global vs. local

​Runtime

​preload

​jsx

​smol

​logLevel

​define

​loader

​telemetry

​env

​console

​console.depth

​Serve

​serve.port

​Test runner

​test.root

​test.preload

​test.pathIgnorePatterns

​test.smol

​test.coverage

​test.coverageThreshold

​test.coverageSkipTestFiles

​test.coverageIgnoreSourcemaps

​test.coveragePathIgnorePatterns

​test.coverageReporter

​test.coverageDir

​test.randomize

​test.seed

​test.rerunEach

​test.retry

​test.concurrentTestGlob

​test.onlyFailures

​test.reporter

​test.reporter.dots

​test.reporter.junit

​Package manager

​install.optional

​install.dev

​install.peer

​install.production

​install.exact

​install.ignoreScripts

​install.concurrentScripts

​install.saveTextLockfile

​install.auto

​install.prefer

​install.frozenLockfile

​install.dryRun

​install.globalDir

​install.globalBinDir

​install.registry

​install.linkWorkspacePackages

​install.scopes

​install.ca and install.cafile

​install.cache

​install.lockfile

​install.linker

​install.globalStore

​install.publicHoistPattern

​install.hoistPattern

​install.logLevel

​install.security.scanner

​install.minimumReleaseAge

​install.minimumReleaseAgeExcludes

​bun run

​run.shell - use the system shell or Bun’s shell

​run.bun - auto alias node to bun

​run.silent - suppress reporting the command being run

​run.elide-lines - truncate filtered output

​run.noOrphans - don’t leave orphan processes behind

Global vs. local

Runtime

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`env`

`console`

`console.depth`

Serve

`serve.port`

Test runner

`test.root`

`test.preload`

`test.pathIgnorePatterns`

`test.smol`

`test.coverage`

`test.coverageThreshold`

`test.coverageSkipTestFiles`

`test.coverageIgnoreSourcemaps`

`test.coveragePathIgnorePatterns`

`test.coverageReporter`

`test.coverageDir`

`test.randomize`

`test.seed`

`test.rerunEach`

`test.retry`

`test.concurrentTestGlob`

`test.onlyFailures`

`test.reporter`

`test.reporter.dots`

`test.reporter.junit`

Package manager

`install.optional`

`install.dev`

`install.peer`

`install.production`

`install.exact`

`install.ignoreScripts`

`install.concurrentScripts`

`install.saveTextLockfile`

`install.auto`

`install.prefer`

`install.frozenLockfile`

`install.dryRun`

`install.globalDir`

`install.globalBinDir`

`install.registry`

`install.linkWorkspacePackages`

`install.scopes`

`install.ca` and `install.cafile`

`install.cache`

`install.lockfile`

`install.linker`

`install.globalStore`

`install.publicHoistPattern`

`install.hoistPattern`

`install.logLevel`

`install.security.scanner`

`install.minimumReleaseAge`

`install.minimumReleaseAgeExcludes`

`bun run`

`run.shell` - use the system shell or Bun’s shell

`run.bun` - auto alias `node` to `bun`

`run.silent` - suppress reporting the command being run

`run.elide-lines` - truncate filtered output

`run.noOrphans` - don’t leave orphan processes behind