# How to Build Single-File Executables with Bun for Distribution

> Easily build single-file executables with Bun for distribution. Compile your JS or TS app into a native binary with the embedded Bun runtime, no separate installation required.

- Repository: [Bun/bun](https://github.com/oven-sh/bun)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Bun’s `--compile` flag bundles your JavaScript or TypeScript application and embeds the Bun runtime into a single native binary that runs on any matching OS/architecture without requiring a separate Bun installation.**

The `oven-sh/bun` repository provides a sophisticated compilation pipeline that transforms your projects into standalone distributables. When you build single-file executables with Bun, the resulting binary contains your bundled code, the JavaScriptCore engine, and optional configuration files, creating a closed-world deployment artifact.

## How Bun Compiles Single-File Executables

Bun’s compilation process follows a three-stage pipeline defined primarily in `src/cli/build_command.zig` (lines 103-167):

1. **Bundling** – The entry point and all dependencies are resolved and bundled. The resolver at `src/resolver/resolver.zig` (line 766) skips external module lookups to ensure a self-contained bundle.
2. **Runtime Embedding** – The bundled output is linked against the Bun runtime binary, creating a native executable (ELF for Linux, PE for Windows, or Mach-O for macOS).
3. **Asset Injection** – Optional files like `.env`, [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/bunfig.toml), or source maps are embedded into the final binary.

The feature is exposed through the `--compile` flag defined in `src/cli/Arguments.zig` (lines 160-210), which implies `--production` and validates that you do not use incompatible flags like `--no-bundle` or `--outdir`.

## Creating Your First Standalone Executable

To compile a basic TypeScript or JavaScript file into a distributable binary, use the `--compile` flag with an entry point:

```bash
bun build src/index.ts --compile --outfile my-app

```

This command produces `./my-app` (or `./my-app.exe` on Windows), a native executable that includes:
- Your minified application code
- The Bun JavaScript runtime (JavaScriptCore)
- Default autoload configurations

The `src/compile_target.zig` module manages the platform-specific compilation targets, ensuring the output matches your host architecture unless overridden.

## Essential Compilation Flags

### Output Configuration

Control the destination and behavior of your compiled binary using these flags validated in `src/cli/build_command.zig`:

- **`--outfile <PATH>`** – Specifies the output filename. Cannot be named `bun`.
- **`--compile-exec-argv <STR>`** – Prepends default arguments to `process.argv` when the binary runs.

```bash
bun build src/cli.ts --compile --compile-exec-argv "--mode=production" --outfile my-cli

```

### Runtime Autoloading

By default, Bun automatically embeds certain configuration files. These options are defined in `src/cli/Arguments.zig`:

- **`--compile-autoload-dotenv`** (default: **enabled**) – Embeds a `.env` file loaded at runtime.
- **`--compile-autoload-bunfig`** (default: **enabled**) – Embeds [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/bunfig.toml).
- **`--compile-autoload-tsconfig`** (default: **disabled**) – Embeds [`tsconfig.json`](https://github.com/oven-sh/bun/blob/main/tsconfig.json).
- **`--compile-autoload-package-json`** (default: **disabled**) – Embeds [`package.json`](https://github.com/oven-sh/bun/blob/main/package.json).

Disable any autoload feature with the `--no-` prefix:

```bash
bun build src/index.ts --compile --no-compile-autoload-dotenv --outfile my-app

```

### Cross-Compilation and Custom Runtimes

Target different operating systems using the `--target` flag or provide a pre-downloaded runtime binary:

```bash

# Cross-compile for Windows from macOS/Linux

bun build src/index.ts --compile --target=win --outfile my-app.exe

# Use a custom runtime binary for offline builds

bun build src/index.ts --compile \
  --compile-executable-path /path/to/bun-windows-x64 \
  --outfile my-app.exe

```

### Windows Metadata

When targeting Windows (`--target=win`), you can embed PE metadata:

- **`--windows-icon <PATH>`** – Sets the application icon (`.ico` file).
- **`--windows-title <STR>`**
- **`--windows-version <STR>`**
- **`--windows-product-name <STR>`**

## Embedding Source Maps for Debugging

For production debugging, include source maps that get embedded by `src/sourcemap/Mapping.zig` (line 228):

```bash
bun build src/index.ts \
  --compile \
  --minify \
  --sourcemap=external \
  --outfile my-app

```

This bundles the source map data directly into the executable, enabling accurate stack traces without external files.

## Complete Distribution Examples

### Basic Web Server Executable

```bash
bun build src/server.ts --compile --minify --outfile my-server
./my-server  # Starts the server immediately

```

### CLI Tool with Default Arguments

```bash
bun build src/tool.ts \
  --compile \
  --compile-exec-argv "--help" \
  --compile-autoload-dotenv \
  --outfile my-tool

```

### Windows Application with Branding

```bash
bun build src/app.ts \
  --compile \
  --target=win \
  --windows-icon=assets/app.ico \
  --windows-title="My Application" \
  --windows-product-name="MyProduct" \
  --outfile dist/my-app.exe

```

## Summary

- **Use `bun build --compile`** to create native executables that embed the Bun runtime along with your JavaScript/TypeScript code.
- **Implementation** resides in `src/cli/build_command.zig` (core logic), `src/cli/Arguments.zig` (flag definitions), and `src/compile_target.zig` (target handling).
- **Autoload flags** (`--compile-autoload-*`) control whether `.env`, [`bunfig.toml`](https://github.com/oven-sh/bun/blob/main/bunfig.toml), and other config files are embedded in the binary.
- **Cross-compilation** is supported via `--target` and `--compile-executable-path` for building Windows binaries on Unix systems.
- **Source maps** can be embedded using `--sourcemap` with compile, handled by `src/sourcemap/Mapping.zig`.

## Frequently Asked Questions

### What is the difference between `bun build` and `bun build --compile`?

Regular `bun build` produces bundled JavaScript files that still require the Bun runtime to execute, while `bun build --compile` generates a native executable (ELF, PE, or Mach-O) with the runtime fully embedded. According to the source in `src/cli/build_command.zig`, the `--compile` flag implies `--production` and produces a closed-world binary that runs independently of any installed JavaScript runtime.

### Can I cross-compile Bun executables for different operating systems?

Yes, use the `--target` flag (e.g., `--target=win`, `--target=linux`, or `--target=darwin`) to specify the destination platform. Bun automatically downloads the appropriate runtime binary for the target, or you can provide a custom path via `--compile-executable-path` for offline cross-compilation scenarios.

### How do I include environment variables in a compiled Bun executable?

Use the `--compile-autoload-dotenv` flag (enabled by default as defined in `src/cli/Arguments.zig`) to embed a `.env` file into the binary. When the executable runs, it automatically loads these variables. Alternatively, disable this with `--no-compile-autoload-dotenv` if you prefer the binary to read from an external `.env` file at runtime.

### Do Bun single-file executables require Node.js or Bun on the target machine?

No. The resulting binary is completely self-contained, including the JavaScriptCore engine and all necessary runtime components. The target machine only needs to match the compiled architecture and operating system; no separate Bun installation, Node.js, or npm dependencies are required to run the executable.