Standalone executables

Bun’s bundler supports the --compile flag for generating standalone binary executables from TypeScript or JavaScript files.

CLI
JavaScript

bun build ./cli.ts --compile --outfile mycli

await Bun.build({
  entrypoints: ["./cli.ts"],
  compile: {
    outfile: "./mycli",
  },
});

cli.ts

console.log("Hello world!");

This bundles cli.ts into an executable binary that can be executed directly:

./mycli

Hello world!

All imported files and packages are bundled into the executable, along with a copy of the Bun runtime. All built-in Bun and Node.js APIs are supported.

Cross-platform compilation

The --target flag allows you to compile standalone executables for a different operating system, architecture, or Bun version than the machine running bun build. Build for Linux x64 (most servers):

CLI
JavaScript

bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp

# For CPU's from before 2013, use the baseline profile (nehalem)
bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp

# For CPU's from 2013 onwards only, use the modern profile (haswell)
# The modern profile is faster, but baseline is more compatible.
bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp

// Standard Linux x64
await Bun.build({
  entrypoints: ["./index.ts"],
  compile: {
    target: "bun-linux-x64",
    outfile: "./myapp",
  },
});

// Baseline (pre-2013 CPUs)
await Bun.build({
  entrypoints: ["./index.ts"],
  compile: {
    target: "bun-linux-x64-baseline",
    outfile: "./myapp",
  },
});

// Modern (2013+ CPUs, faster)
await Bun.build({
  entrypoints: ["./index.ts"],
  compile: {
    target: "bun-linux-x64-modern",
    outfile: "./myapp",
  },
});

Build for Linux ARM64 (like Graviton or Raspberry Pi):

CLI
JavaScript

# Note: default architecture is x64 if no architecture is specified.
bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp

await Bun.build({
  entrypoints: ["./index.ts"],
  compile: {
    target: "bun-linux-arm64",
    outfile: "./myapp",
  },
});

Build for Windows x64:

CLI
JavaScript

bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp

# For CPU's from before 2013, use the baseline profile (nehalem)
bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp

# For CPU's from 2013 onwards only, use the modern profile (haswell)
bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp

# Note: if no .exe extension is provided, Bun will automatically add it for Windows executables

// Standard Windows x64
await Bun.build({
  entrypoints: ["./path/to/my/app.ts"],
  compile: {
    target: "bun-windows-x64",
    outfile: "./myapp", // .exe added automatically
  },
});

// Baseline or modern profiles
await Bun.build({
  entrypoints: ["./path/to/my/app.ts"],
  compile: {
    target: "bun-windows-x64-baseline",
    outfile: "./myapp",
  },
});

Build for Windows ARM64:

CLI
JavaScript

bun build --compile --target=bun-windows-arm64 ./path/to/my/app.ts --outfile myapp

# note: if no .exe extension is provided, Bun will automatically add it for Windows executables

await Bun.build({
  entrypoints: ["./path/to/my/app.ts"],
  compile: {
    target: "bun-windows-arm64",
    outfile: "./myapp", // .exe added automatically
  },
});

Build for macOS ARM64:

CLI
JavaScript

bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp

await Bun.build({
  entrypoints: ["./path/to/my/app.ts"],
  compile: {
    target: "bun-darwin-arm64",
    outfile: "./myapp",
  },
});

Build for macOS x64:

CLI
JavaScript

bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp

await Bun.build({
  entrypoints: ["./path/to/my/app.ts"],
  compile: {
    target: "bun-darwin-x64",
    outfile: "./myapp",
  },
});

Available targets

The following targets are available:

Target	OS	Architecture	Profile
`bun-linux-x64`	Linux	x64	default
`bun-linux-x64-baseline`	Linux	x64	baseline (pre-2013)
`bun-linux-x64-modern`	Linux	x64	modern (2013+)
`bun-linux-arm64`	Linux	ARM64	default
`bun-windows-x64`	Windows	x64	default
`bun-windows-x64-baseline`	Windows	x64	baseline (pre-2013)
`bun-windows-x64-modern`	Windows	x64	modern (2013+)
`bun-windows-arm64`	Windows	ARM64	default
`bun-darwin-arm64`	macOS	ARM64	default
`bun-darwin-x64`	macOS	x64	default

Embedding files

You can embed files into the executable by importing them in your code. The bundler will automatically include them.

import icon from "./icon.png";
import styles from "./styles.css";

console.log(icon); // path to the embedded file

These files are extracted to a temporary directory at runtime and can be accessed via their import paths.

Configuration options

minify

You can minify the bundled code:

bun build --compile --minify ./index.ts --outfile myapp

sourcemap

Generate source maps for debugging:

bun build --compile --sourcemap=external ./index.ts --outfile myapp

This creates a .map file alongside your executable.

splitting

Code splitting is not supported when using --compile since the output is a single executable.

Environment variables

By default, executables do NOT load .env files. You can change this behavior:

bun build --compile --env-file=.env ./index.ts --outfile myapp

Or inline environment variables at build time:

bun build --compile --define 'process.env.API_KEY="secret"' ./index.ts --outfile myapp

Command-line arguments

Your executable receives command-line arguments via process.argv:

cli.ts

const args = process.argv.slice(2);
console.log("Arguments:", args);

./mycli arg1 arg2 --flag
# Arguments: [ 'arg1', 'arg2', '--flag' ]

Size considerations

Standalone executables include the Bun runtime, so they start at around 50-90 MB depending on the target platform. This size includes:

The Bun JavaScript runtime
JavaScriptCore engine
Your bundled code and dependencies
Any embedded assets

You can reduce size with:

--minify to compress your code
--external to exclude large dependencies
Tree shaking (automatic) to remove unused code

Deployment

Standalone executables are single-file deployables with no dependencies:

Build for your target platform
Copy the executable to your server
Set executable permissions (Unix): chmod +x myapp
Run: ./myapp

No need to install Bun or Node.js on the deployment target.

Troubleshooting

Large binary size

If your executable is larger than expected:

Check for unintended imports of large dependencies
Use --external for dependencies you want to load at runtime
Enable --minify to compress code

Runtime errors

If your executable fails at runtime:

Test your code with bun run before compiling
Check that all file paths are relative or properly configured
Verify embedded assets are imported correctly

Cross-compilation issues

When building for a different platform:

Ensure you’re using the correct --target value
Test on the target platform before deploying
Some native modules may not work when cross-compiled

Examples

Simple CLI tool

cli.ts

#!/usr/bin/env bun
import { parseArgs } from "util";

const { values } = parseArgs({
  args: process.argv.slice(2),
  options: {
    name: { type: "string", short: "n" },
  },
});

console.log(`Hello, ${values.name || "World"}!`);

bun build --compile ./cli.ts --outfile hello
./hello --name Bun
# Hello, Bun!

HTTP server

server.ts

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

console.log(`Server running at http://localhost:${server.port}`);

bun build --compile ./server.ts --outfile server
./server
# Server running at http://localhost:3000

With embedded assets

app.ts

import logo from "./logo.png";
import template from "./template.html" with { type: "text" };

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/") {
      return new Response(template, {
        headers: { "Content-Type": "text/html" },
      });
    }
    if (url.pathname === "/logo.png") {
      return new Response(Bun.file(logo));
    }
    return new Response("Not found", { status: 404 });
  },
});

console.log(`Server running at http://localhost:${server.port}`);

bun build --compile ./app.ts --outfile app
./app

Core

Features

Migration

Standalone executables

Cross-platform compilation

Available targets

Embedding files

Configuration options

minify

sourcemap

splitting

Environment variables

Command-line arguments

Size considerations

Deployment

Troubleshooting

Large binary size

Runtime errors

Cross-compilation issues

Examples

Simple CLI tool

HTTP server

With embedded assets

Build docs developers (and LLMs) love

Core

Features

Migration

Documentation Index

​Cross-platform compilation

​Available targets

​Embedding files

​Configuration options

​minify

​sourcemap

​splitting

​Environment variables

​Command-line arguments

​Size considerations

​Deployment

​Troubleshooting

​Large binary size

​Runtime errors

​Cross-compilation issues

​Examples

​Simple CLI tool

​HTTP server

​With embedded assets

Build docs developers (and LLMs) love

Cross-platform compilation

Available targets

Embedding files

Configuration options

minify

sourcemap

splitting

Environment variables

Command-line arguments

Size considerations

Deployment

Troubleshooting

Large binary size

Runtime errors

Cross-compilation issues

Examples

Simple CLI tool

HTTP server

With embedded assets