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

# Bun Runtime

> Execute JavaScript/TypeScript files, package.json scripts, and executable packages with Bun's fast runtime.

The Bun Runtime is designed to start fast and run fast.

Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), developed by Apple for Safari. JavaScriptCore usually starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. Bun's transpiler and runtime are written in Rust. On Linux, Bun starts [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.

| Command | Time |
| - | - |
| `bun hello.js` | `5.2ms` |
| `node hello.js` | `25.1ms` |

The benchmark runs a Hello World script on Linux.

## Run a file

Use `bun run` to execute a source file.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run index.js
```

Bun supports TypeScript and JSX with no configuration. Bun transpiles every file on the fly with its native [transpiler](https://bun.com/docs/runtime/transpiler.md) before running it.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run index.js
bun run index.jsx
bun run index.ts
bun run index.tsx
```

Alternatively, you can omit the `run` keyword and use the "naked" command; it behaves identically.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun index.tsx
bun index.js
```

### `--watch`

To run a file in watch mode, use the `--watch` flag.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --watch run index.tsx
```

> [!NOTE]
>
> When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
>
> ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
> bun --watch run dev # ✔️ do this
> bun run dev --watch # ❌ don't do this
> ```
>
> `bun` ignores flags at the end of the command and passes them through to the `"dev"` script itself.

## Run a `package.json` script

> [!NOTE]
>
> Compare to `npm run <script>` or `yarn <script>`

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun [bun flags] run <script> [script flags]
```

Your `package.json` can define named `"scripts"` that correspond to shell commands.

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  // ... other fields
  "scripts": {
    "clean": "rm -rf dist && echo 'Done.'",
    "dev": "bun server.ts"
  }
}
```

Use `bun run <script>` to execute these scripts.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run clean
rm -rf dist && echo 'Done.'
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
Done.
```

Bun executes the script command in a subshell. On Linux & macOS, it checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`. On Windows, it uses the [Bun Shell](https://bun.com/docs/runtime/shell.md) to support bash-like syntax and many common commands.

> [!NOTE]
>
> ⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.

You can also run scripts with the shorter command `bun <script>`. If a built-in `bun` command has the same name, the built-in command takes precedence; use the explicit `bun run <script>` to run your package script instead.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run dev
```

To see a list of available scripts, run `bun run` without any arguments.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
...
package.json scripts (2 found):
  $ bun run clean
    rm -rf dist && echo 'Done.'

  $ bun run dev
    bun server.ts
```

Bun respects lifecycle hooks. For instance, `bun run clean` runs `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun does not run the script itself.

### `--bun`

It's common for `package.json` scripts to reference locally-installed CLIs like `vite` or `next`. These CLIs are often JavaScript files marked with a [shebang](https://en.wikipedia.org/wiki/Shebang_\(Unix\)) to indicate that they should be executed with `node`.

```js cli.js icon="https://mintcdn.com/bun-1dd33a4e/JUhaF6Mf68z_zHyy/icons/javascript.svg?fit=max&auto=format&n=JUhaF6Mf68z_zHyy&q=85&s=5148f41bbc784f9828f1363dab67340f" theme={"theme":{"light":"github-light","dark":"dracula"}}
#!/usr/bin/env node

// do stuff
```

By default, Bun respects this shebang and executes the script with `node`. The `--bun` flag overrides it: the CLI runs with Bun instead of Node.js.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run --bun vite
```

### Filtering

In a monorepo, the `--filter` argument runs a script in many packages at once.

`bun run --filter <pattern> <script>` executes `<script>` in every package selected by `<pattern>`. The pattern can be a package name glob, a `./path`, a `{dir}` directory or a dependency relation like `foo...`.
For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run --filter 'ba*' <script>
```

executes `<script>` in both `bar` and `baz`, but not in `foo`.

See [`--filter`](https://bun.com/docs/pm/filter#running-scripts-with-filter).

## `bun run -` to pipe code from stdin

`bun run -` reads JavaScript, TypeScript, TSX, or JSX from stdin and executes it without writing to a temporary file first.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
echo "console.log('Hello')" | bun run -
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
Hello
```

You can also use `bun run -` to redirect files into Bun. For example, to run a `.js` file as if it were a `.ts` file:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
bun run - < secretly-typescript.js
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
This is TypeScript!
```

`bun run -` treats all input as TypeScript with JSX support.

## `bun run --console-depth`

Control the depth of object inspection in console output with the `--console-depth` flag.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --console-depth 5 run index.tsx
```

`--console-depth` sets how deeply Bun displays nested objects in `console.log()` output. The default depth is `2`. Higher values show more nested properties but may produce verbose output for complex objects.

```ts console.ts icon="https://mintcdn.com/bun-1dd33a4e/JUhaF6Mf68z_zHyy/icons/typescript.svg?fit=max&auto=format&n=JUhaF6Mf68z_zHyy&q=85&s=7ac549adaea8d5487d8fbd58cc3ea35b" theme={"theme":{"light":"github-light","dark":"dracula"}}
const nested = { a: { b: { c: { d: "deep" } } } };
console.log(nested);
// With --console-depth 2 (default): { a: { b: { c: [Object] } } }
// With --console-depth 4: { a: { b: { c: { d: 'deep' } } } }
```

## `bun run --smol`

In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --smol run index.tsx
```

`--smol` makes the garbage collector run more frequently, which can slow down execution. Bun adjusts the garbage collector's heap size based on the available memory (accounting for cgroups and other memory limits) with and without the `--smol` flag. The flag is therefore mostly useful when you want the heap to grow more slowly.

## Resolution order

Bun always executes absolute paths and paths starting with `./` or `.\\` as source files. Unless you use `bun run`, a name with an allowed extension resolves to the file rather than a `package.json` script.

When a `package.json` script and a file have the same name, `bun run` prefers the script. The full resolution order is:

1. `package.json` scripts: `bun run build`
2. Source files: `bun run src/main.js`
3. Binaries from project packages: `bun add eslint && bun run eslint`
4. (`bun run` only) System commands: `bun run ls`

***

# CLI Usage

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run <file or script>
```

### General Execution Options

**--silent** `boolean`

Don't print the script command

**--if-present** `boolean`

Exit without an error if the entrypoint does not exist

**--eval** `string`

Evaluate argument as a script. Alias: `-e`

**--print** `string`

Evaluate argument as a script and print the result. Alias: `-p`

**--help** `boolean`

Display this menu and exit. Alias: `-h`

### Workspace Management

**--elide-lines** `number` (default: 10)

Number of lines of script output shown when using --filter (default: 10). Set to 0 to show all lines

**--filter** `string`

Run a script in all workspace packages matching the pattern. Alias: `-F`

**--workspaces** `boolean`

Run a script in all workspace packages (from the `workspaces` field in `package.json`)

**--parallel** `boolean`

Run multiple scripts or workspace scripts concurrently with prefixed output

**--sequential** `boolean`

Run multiple scripts or workspace scripts one after another with prefixed output

**--no-exit-on-error** `boolean`

When using `--parallel` or `--sequential`, continue running other scripts when one fails

### Runtime & Process Control

**--bun** `boolean`

Force a script or package to use Bun's runtime instead of Node.js (via symlinking node). Alias: `-b`

**--shell** `string`

Control the shell used for `package.json` scripts. Supports either `bun` or `system`

**--interactive** `boolean`

Open the Node.js-compatible REPL (`node:repl`). When combined with `-e`, starts the REPL and
then evaluates the script. Under `--interactive`, `-e` is raw JavaScript (matching&#x20;
`node -i -e`). Use `bun repl` for TypeScript. Distinct from `bun repl`, which is
Bun's native REPL.

**--smol** `boolean`

Use less memory, but run garbage collection more often

**--expose-gc** `boolean`

Expose `gc()` on the global object. Has no effect on `Bun.gc()`

**--no-deprecation** `boolean`

Silence all deprecation warnings

**--throw-deprecation** `boolean`

Throw deprecation warnings as errors

**--title** `string`

Set the process title

**--zero-fill-buffers** `boolean`

Force `Buffer.allocUnsafe(size)` to be zero-filled

**--no-addons** `boolean`

Throw an error if `process.dlopen` is called, and disable export condition `node-addons`

**--unhandled-rejections** `string`

One of `strict`, `throw`, `warn`, `none`, or&#x20;
`warn-with-error-code`

**--console-depth** `number` (default: 2)

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

### Development Workflow

**--watch** `boolean`

Automatically restart the process on file change

**--watch-kill-signal** `string` (default: SIGTERM)

Signal whose handlers run when --watch restarts the process

**--hot** `boolean`

Enable auto reload in the Bun runtime, test runner, or bundler

**--no-clear-screen** `boolean`

Disable clearing the terminal screen on reload when --hot or --watch is enabled

### Debugging

**--inspect** `string`

Activate Bun's debugger

**--inspect-wait** `string`

Activate Bun's debugger, wait for a connection before executing

**--inspect-brk** `string`

Activate Bun's debugger, set breakpoint on first line of code and wait

### Dependency & Module Resolution

**--preload** `string`

Import a module before Bun loads other modules. Alias: `-r`

**--require** `string`

Alias of --preload, for Node.js compatibility

**--import** `string`

Alias of --preload, for Node.js compatibility

**--no-install** `boolean`

Disable auto install in the Bun runtime

**--install** `string` (default: auto)

Configure auto-install behavior. One of `auto` (default, auto-installs when no node\_modules),&#x20;
`fallback` (missing packages only), `force` (always)

**-i** `boolean`

Auto-install dependencies during execution. Equivalent to --install=fallback

**--prefer-offline** `boolean`

Skip staleness checks for packages in the Bun runtime and resolve from disk

**--prefer-latest** `boolean`

Use the latest matching versions of packages in the Bun runtime, always checking npm

**--conditions** `string`

Pass custom conditions to resolve

**--main-fields** `string`

Main fields to lookup in `package.json`

**--preserve-symlinks** `boolean`

Preserve symlinks when resolving files

**--preserve-symlinks-main** `boolean`

Preserve symlinks when resolving the main entry point

**--extension-order** `string` (default: .tsx,.ts,.jsx,.cts,.cjs,.js,.mjs,.mts,.json,.node)

Defaults to: `.tsx,.ts,.jsx,.cts,.cjs,.js,.mjs,.mts,.json,.node`

### Transpilation & Language Features

**--tsconfig-override** `string`

Specify custom `tsconfig.json`. Default `$cwd/tsconfig.json`

**--define** `string`

Substitute K:V while parsing, e.g. `--define process.env.NODE_ENV:"development"`. Bun parses values as
JSON. Alias: `-d`

**--drop** `string`

Remove function calls, e.g. `--drop=console` removes all `console.*` calls

**--loader** `string`

Parse files with `.ext:loader`, e.g. `--loader .js:jsx`. Valid loaders: `js`,&#x20;
`jsx`, `ts`, `tsx`, `json`, `toml`, `text`,&#x20;
`file`, `wasm`, `napi`. Alias: `-l`

**--no-macros** `boolean`

Disable macro execution in the bundler, transpiler and runtime

**--jsx-factory** `string`

Changes the function called when compiling JSX elements using the classic JSX runtime

**--jsx-fragment** `string`

Changes the function called when compiling JSX fragments

**--jsx-import-source** `string` (default: react)

Declares the module specifier used to import the jsx and jsxs factory functions. Default: `react`

**--jsx-runtime** `string` (default: automatic)

`automatic` (default) or `classic`

**--jsx-side-effects** `boolean`

Treat JSX elements as having side effects (disable pure annotations)

**--ignore-dce-annotations** `boolean`

Ignore tree-shaking annotations such as `@PURE`

### Networking & Security

**--port** `number`

Set the default port for `Bun.serve`

**--fetch-preconnect** `string`

Preconnect to a URL while code is loading

**--max-http-header-size** `number` (default: 16384)

Set the maximum size of HTTP headers in bytes. Default is 16KiB

**--dns-result-order** `string` (default: verbatim)

Set the default order of DNS lookup results. Valid orders: `verbatim` (default), `ipv4first`,&#x20;
`ipv6first`

**--use-system-ca** `boolean`

Use the system's trusted certificate authorities

**--use-openssl-ca** `boolean`

Use OpenSSL's default CA store

**--use-bundled-ca** `boolean`

Use bundled CA store

**--redis-preconnect** `boolean`

Preconnect to `$REDIS_URL` at startup

**--sql-preconnect** `boolean`

Preconnect to PostgreSQL at startup

**--user-agent** `string`

Set the default User-Agent header for HTTP requests

### Global Configuration & Context

**--env-file** `string`

Load environment variables from the specified file(s)

**--cwd** `string`

Absolute path to resolve files & entrypoints from. This only changes the process' cwd

**--config** `string`

Specify path to Bun config file. Default `$cwd/bunfig.toml`. Alias: `-c`

## Examples

Run a JavaScript or TypeScript file:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run ./index.js
bun run ./index.tsx
```

Run a package.json script:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run dev
bun run lint
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.