# dart compile

> Command-line tool for compiling Dart source code.



This guide describes how to use the `dart compile` command
to compile a Dart program to a target platform.

## Overview

:::note
If your package or any of its dependencies has [build hooks][],
you must use the [`dart build cli`][] command.
The `dart compile exe` and `dart compile aot-snapshot` commands don't
run build hooks and fail if hooks are present.
:::

Use the `dart compile` command to compile
a Dart program to a [target platform][].
The output—which you specify with a subcommand—can
either include a [Dart runtime][] or be a _module_
(also known as a _snapshot_).

:::tip
To learn more information about this and other `dart` commands,
check out the [Dart command-line tool page](/tools/dart-tool).
:::


The following example uses the `exe` subcommand
to produce a self-contained executable file (`myapp.exe`):

```console
$ dart compile exe bin/myapp.dart
```

The output is similar to the following:

```console
Generated: /Users/me/myapp/bin/myapp.exe
```

The next example uses the `aot-snapshot` subcommand to
produce an ahead-of-time (AOT) compiled module (`myapp.aot`):

```console
$ dart compile aot-snapshot bin/myapp.dart
```

The output is similar to the following:

```console
Generated: /Users/me/myapp/bin/myapp.aot
```

Use the [`dartaotruntime` command][dartaotruntime]
(which provides a [Dart runtime][])
to run the AOT module:

```console
$ dartaotruntime bin/myapp.aot
```

To specify the path to the output file,
use the `-o` or `--output` option:

```console
$ dart compile exe bin/myapp.dart -o bin/runme
```

For more options and usage information,
run `dart compile SUBCOMMAND --help`,
replacing `SUBCOMMAND` with a subcommand such as `exe` or `wasm`:

```console
$ dart compile exe --help
```

:::note
You don't need to compile Dart programs before running them.
Instead, you can use the [`dart run` command][dart-run],
which uses the Dart VM's just-in-time (JIT) compiler—a
feature that's especially useful during development.
For more information on AOT and JIT compilation,
refer to the [platforms discussion][target platform].
:::

Refer to the [native_app][] sample for a simple example of using `dart compile`
to compile a native app,
followed by examples of running the app.

[build hooks]: /tools/hooks
[`dart build cli`]: /tools/dart-build
[target platform]: /overview#platform
[dartaotruntime]: /tools/dartaotruntime
[native_app]: https://github.com/dart-lang/samples/tree/main/native_app
[dart-run]: /tools/dart-run

## Subcommands

The following table shows the subcommands of `dart compile`.

<table class="table table-striped nowrap">
  <tr>
    <th> Subcommand </th> <th> Output </th> <th> Description </th>
  </tr>
  <tr>
    <td> <a href="#exe"><code>exe</code></a> </td>
    <td> <span style="white-space: nowrap">Self-contained</span> executable </td>
    <td> A standalone, architecture-specific executable file containing the source code
      compiled to machine code and a small <a href="/overview#runtime">Dart runtime</a>.
    </td>
  </tr>
  <tr>
    <td style="white-space: nowrap"> <a href="#aot-snapshot"><code>aot-snapshot</code></a> </td>
    <td style="white-space: nowrap"> AOT module </td>
    <td> An architecture-specific file containing the source code
      compiled to machine code, without a Dart runtime.
    </td>
  </tr>
  <tr>
    <td> <a href="#jit-snapshot"><code>jit-snapshot</code></a> </td>
    <td> JIT module </td>
    <td> An architecture-specific file with
      an intermediate representation of all source code,
      plus an optimized representation of the source code
      that executed during a training run of the program.
      JIT-compiled code can have faster peak performance than AOT code
      if the training data is good.
    </td>
  </tr>
  <tr>
    <td> <a href="#kernel"><code>kernel</code></a> </td>
    <td> Kernel module </td>
    <td> A portable,
      <a href="https://github.com/dart-lang/sdk/blob/main/pkg/kernel/binary.md">intermediate representation</a>
      of the source code.
    </td>
  </tr>
  <tr>
    <td> <a href="#js"><code>js</code></a> </td>
    <td> JavaScript </td>
    <td> A deployable JavaScript file (<code>.js</code>)
      and source map (<code>.js.map</code>),
      compiled from the source code.
    </td>
  </tr>
  <tr>
    <td> <a href="#wasm"><code>wasm</code></a> </td>
    <td> WebAssembly </td>
    <td> A WebAssembly module (<code>.wasm</code>),
      companion JavaScript runtime (<code>.mjs</code>),
      and source map (<code>.wasm.map</code>).
    </td>
  </tr>
</table>


## Types of output

The following sections have details about each type of output
that `dart compile` can produce.


### Self-contained executables (`exe`) {:#exe}

The `exe` subcommand produces a standalone executable for
Windows, macOS, or Linux.
A _standalone executable_ is native machine code that's compiled from
the specified Dart file and its dependencies,
plus a small [Dart runtime][] that handles
type checking and garbage collection.

You can distribute and run the output file like you would
any other executable file.

Compile your app and set the output file:

```console
$ dart compile exe bin/myapp.dart -o /tmp/myapp
```

When successful, this command outputs the following:

```console
Generated: /tmp/myapp
```

Run your compiled executable:

```console
$ /tmp/myapp
```

<a id="cross-compilation" aria-hidden="true"></a>

#### Cross-compilation {: #cross-compilation-exe }

:::version-note
Support for Linux ARM64 and x64 cross-compilation was introduced in Dart 3.8.

Support for Linux ARM and RISCV64 was introduced in Dart 3.9.
:::

The following table shows which 64-bit host operating systems support
cross-compilation to which targets:



| 64-bit host OS | Linux ARM | Linux ARM64 | Linux RISCV64 | Linux x64 |
|----------------|-----------|-------------|---------------|-----------|
| Linux          |   <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>   |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>    |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>      |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>  |
| macOS          |   <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>   |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>    |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>      |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>  |
| Windows        |   <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>   |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>    |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>      |    <span class="material-symbols system-support" title="Supported" aria-label="Supported">done</span>  |

{:.table .table-striped .nowrap}

To use cross-compilation, include the following flags:

`--target-os=linux`
: The target operating system for the compiled executable.
  Cross-compilation supports only Linux as a target operating system.

`--target-arch=value`
: The target architecture for the compiled executable.
  The value for this flag can be one of the following architectures:

  - `arm`: 32-bit ARM processor
  - `arm64`: 64-bit ARM processor
  - `riscv64`: 64-bit RISC-V (RV64GC) processor
  - `x64`: x86-64 processor

The following command demonstrates how to cross-compile a
standalone executable for a 64-bit Linux system:

```console
$ dart compile exe \
  --target-os=linux \
  --target-arch=x64 \
  hello.dart
```

Internally, this command downloads additional Dart SDK binaries and
caches them in the `~/.dart` directory.

Here's a sample output with the `--verbose` flag specified with
the command:

```console
Downloading https://storage.googleapis.com/dart-archive/channels/dev/signed/hash/...4864.../sdk/gen_snapshot_macos_arm64_linux_x64...
Downloading https://storage.googleapis.com/dart-archive/channels/dev/raw/hash/...64e44.../sdk/dartaotruntime_linux_x64...
Specializing Platform getters for target OS linux.
Generating AOT kernel dill.
Compiling /tmp/hello.dart to /tmp/hello.exe using format Kind.exe:
Generating AOT snapshot. path/to/dir/.dart/3.8.0-265.0.dev/gen_snapshot_macos_arm64_linux_x64 []
Generating executable.
Marking binary executable.
Generated: /tmp/hello.exe
```

#### Signing

Executables created with `dart compile exe`
support signing on macOS and Windows.

To learn more about platform-specific code signing,
refer to the platform documentation for those operating systems:

* Windows [`SignTool.exe` documentation][]
* [Apple Code Signing guide][]

[`SignTool.exe` documentation]: https://docs.microsoft.com/dotnet/framework/tools/signtool-exe
[Apple Code Signing guide]: https://developer.apple.com/support/code-signing/

#### Known limitations {: #known-limitations }

The `exe` subcommand has the following known limitations:

* No support for `dart:mirrors` and `dart:developer`.
  For a complete list of the core libraries you can use,
  refer to the [Multi-platform][] and [Native platform][] library tables.

* Cross-compilation is supported, but the target OS is limited to Linux.
  To learn more, refer to [Cross-compilation][].

[Multi-platform]: /libraries#multi-platform-libraries
[Native platform]: /libraries#native-platform-libraries
[Cross-compilation]: #cross-compilation-exe

### AOT modules (`aot-snapshot`) {:#aot-snapshot}

Use AOT modules to reduce disk space requirements when distributing
multiple command-line apps. The `aot-snapshot` subcommand produces an
output file specific to the current architecture on which you compile
your app.

For example, if you use macOS to create a `.aot` file,
then that file can run on macOS only.
Dart supports AOT modules on Windows, macOS, and Linux.

Compile your app and set the output file:

```console
$ dart compile aot-snapshot bin/myapp.dart
```

When successful, this command outputs the following:

```console
Generated: /Users/me/myapp/bin/myapp.aot
```

Run your compiled app from your project root directory:

```console
$ dartaotruntime bin/myapp.aot
```

To learn more, refer to the
[`dartaotruntime` documentation][dartaotruntime].



#### Cross-compilation {: #cross-compilation-aot }

Cross-compilation support for the `aot-snapshot` subcommand
is the same as what's available for the `exe` subcommand.
For more information, refer to
[Self-contained executables (`exe`)][cross-compile-exe].

[cross-compile-exe]: #cross-compilation-exe

#### Known limitations {: #known-limitations-aot }

The `aot-snapshot` subcommand has the same limitations
as the `exe` subcommand. For more information, refer to
[Self-contained executables (`exe`)][known-limitations-exe].

[known-limitations-exe]: #known-limitations

### JIT modules (`jit-snapshot`) {:#jit-snapshot}

JIT modules include all the parsed classes and compiled code that's
generated during a training run of a program.

Compile a JIT module from a training run:

```console
$ dart compile jit-snapshot bin/myapp.dart
```

The output is similar to the following:

```console
Compiling bin/myapp.dart to jit-snapshot file bin/myapp.jit.
Hello world!
```

Run the compiled JIT module:

```console
$ dart run bin/myapp.jit
```

The output is similar to the following:

```console
Hello world!
```

When running from an application module,
the Dart VM doesn't need to parse or compile classes and functions that
were already used during the training run,
so the VM starts running your code sooner.

These modules are architecture-specific,
unlike modules produced by using the
[`kernel` subcommand][kernel-subcommand].


### Portable modules (`kernel`) {:#kernel}

Use the `kernel` subcommand to package an app into a
single, portable file that
runs on all operating systems and CPU architectures.
A kernel module contains a binary form of the abstract syntax tree
([Kernel AST][]) for a Dart program.

Create a kernel module:

```console
$ dart compile kernel bin/myapp.dart
```

The output is similar to the following:

```console
Compiling bin/myapp.dart to kernel file bin/myapp.dill.
```

Run the compiled kernel module:

```console
$ dart run bin/myapp.dill
```

Although kernel modules have reduced startup time compared to Dart code,
they can have much slower startup than architecture-specific AOT output formats.

[kernel-subcommand]: #kernel
[Kernel AST]: https://github.com/dart-lang/sdk/blob/main/pkg/kernel/README.md


### JavaScript (`js`) {:#js}

The `js` subcommand compiles Dart code to deployable JavaScript.
By default, the compiler outputs both the JavaScript file (`.js`)
and a source map file (`.js.map`).

:::note
Use the [`webdev` tool][webdev] rather than running the
Dart-to-JavaScript compiler directly.

* The [`webdev build`][] command, by default,
  produces minified, deployable JavaScript.

* The [`webdev serve`][] command, by default,
  produces JavaScript modules for running and debugging during development.
:::

#### Options {:#prod-compile-options}

The `dart compile js` command has multiple options
to customize javascript code compilation.

* [Basic options](#basic-options)
* [Path and environment options](#path-and-environment-options)
* [Display options](#display-options)
* [Analysis options](#analysis-options)

###### Basic options

Common options include:

`-o <file>` or `--output=<file>`
: Generates the output into `<file>`. 
  If not specified, the output goes in a file named `out.js`.

`--enable-asserts`
: Enables assertion checking.

`-O{0|1|2|3|4}`
: Controls optimizations to reduce file size and
  improve code performance.
  To learn more about these optimizations, 
  run `dart compile js -hv`.

  * `-O0`: Disables many optimizations.
  * `-O1`: Enables default optimizations.
  * `-O2`: Enables `-O1` optimizations, plus additional ones
    (such as minification) that respect the language semantics and
    are safe for all programs.

    :::note
    With `-O2`, string representations of types are no longer the same as
    those in the Dart VM when compiled with the development JavaScript compiler.
    :::
  * `-O3`: Enables `-O2` optimizations, plus omits implicit type checks.
    
    :::warning
    Omitting type checks can cause your app to crash due to type errors.
    Before using `-O3`, **test using `-O2`** to ensure that your app
    **never** throws a subtype of `Error` (such as `TypeError`).
    :::
  * `-O4`: Enables more aggressive optimizations than `-O3`,
    but with the same assumptions.
    
    :::warning
    The `-O4` optimizations are susceptible to variations in input data.
    Before relying on `-O4`, **test for edge cases in user input**.
    :::

`--no-source-maps`
: Don't generate a source map file.
  By default, `dart compile js` automatically outputs a `.js.map`
  source map file alongside the generated JavaScript code.
  Use this flag to disable source map generation.
  For security and privacy considerations when deploying source maps,
  see [Web deployment][manage-source-maps].

`-h` or `--help`
: Displays help. To get information about all options, use `-hv`.


###### Path and environment options

Some other handy options include:

`--packages=<path>`
: Specifies the path to the package resolution configuration file.
  For more information, check out the
  [Dart package configuration file][] specification.

`-D<flag>=<value>`
: Defines an environment declaration and value pair
  which can be accessed with 
  [`String.fromEnvironment`][], [`int.fromEnvironment`][], 
  [`bool.fromEnvironment`][], or [`bool.hasEnvironment`][].
  To learn more about environment declarations,
  see [Configuring apps with compilation environment declarations][].

`--version`
: Displays version information for `dart`.

[Dart package configuration file]: https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md
[`String.fromEnvironment`]: https://api.dart.dev/dart-core/String/String.fromEnvironment.html
[`int.fromEnvironment`]: https://api.dart.dev/dart-core/int/int.fromEnvironment.html
[`bool.fromEnvironment`]: https://api.dart.dev/dart-core/bool/bool.fromEnvironment.html
[`bool.hasEnvironment`]: https://api.dart.dev/dart-core/bool/bool.hasEnvironment.html
[Configuring apps with compilation environment declarations]: /libraries/core/environment-declarations
[manage-source-maps]: /web/deployment#manage-source-maps-and-unneeded-build-files

###### Display options

The following options help you control the compiler output.

`--suppress-warnings`
: Doesn't display warnings.

`--suppress-hints`
: Doesn't display hints.

`--terse`
: Emits diagnostics, 
  without suggesting how to get rid of the diagnosed problems.

`-v` or `--verbose`
: Displays lots of information.


###### Analysis options

The following options control the analysis performed on Dart code.

`--fatal-warnings`
: Treat warnings as compilation errors.

`--enable-diagnostic-colors`
: Adds colors to diagnostic messages.

`--show-package-warnings`
: Shows warnings and hints generated from packages.

`--csp`
: Disables dynamic generation of code in the generated output.
  This is necessary to satisfy CSP restrictions
  (see [W3C Content Security Policy.](https://www.w3.org/TR/CSP/))

`--dump-info`
: Generates a file (with the suffix `.info.json`)
  that contains information about the generated code.
  You can inspect the generated file with tools in
  [dart2js_info](https://github.com/dart-lang/sdk/blob/main/pkg/dart2js_info/README.md).

`--[no-]deprecated-js-interop`
: Enables or disables support for the deprecated `dart:*` JS interop
  and web libraries (`dart:html`, `dart:indexed_db`,
  `dart:js`, `dart:js_util`, `dart:svg`, `dart:web_audio`, and
  `dart:web_gl`), as well as packages that import them
  (such as `package:js`).
  Enabled by default (`--deprecated-js-interop`).
  When you pass the `--no-deprecated-js-interop` flag,
  importing any of these libraries results in a compile-time error
  that reports the shortest import paths to the deprecated libraries.
  In addition, their `dart.library.*` environment conditions
  (such as `dart.library.html` and `dart.library.js_util`)
  evaluate to `false` in conditional imports and [`bool.fromEnvironment`][].
  For details, refer to
  [Disallow deprecated JS interop libraries][disallow-legacy].

[disallow-legacy]: /interop/js-interop/past-js-interop#disallow-deprecated-js-interop


#### Compile a web app

For example, to compile a Dart application to optimized JavaScript, run
the following command:

```console
$ dart compile js -O2 -o out/main.js web/main.dart
```


#### Improve production web compilation {:#helping-generate-efficient-code}

Follow these practices to improve type inference, reduce file size, and
improve JavaScript performance:

* Don't use `Function.apply()`.
* Don't override `noSuchMethod()`.
* Avoid setting variables to `null`.
* Be consistent with the types of arguments
  you pass into each function or method.

:::tip
Don't worry about the size of your app's included libraries.
The production compiler performs tree shaking to omit
unused classes, functions, and methods.
Import the libraries you think you'll need,
and let the compiler get rid of what it doesn't need.
:::

To learn more about building and deploying JavaScript applications,
refer to [Web deployment][].

[Web deployment]: /web/deployment


### WebAssembly (`wasm`) {:#wasm}

The `wasm` subcommand compiles Dart code ahead-of-time (AOT) to a
WebAssembly (WasmGC) module (`dart2wasm`).
By default, the compiler generates the `.wasm` module,
a companion `.mjs` JavaScript runtime file,
and a `.wasm.map` source map file.

For example, run the following command to compile a Dart web application to
optimized WebAssembly:

```console
$ dart compile wasm -O2 -o site/main.wasm web/main.dart
```

| Option | Description |
| :--- | :--- |
| `-O0` to `-O4` | Controls compiler optimizations for code size and execution speed (`-O1` is the default, `-O2` adds minification and omits error details, `-O3` omits implicit type checks, and `-O4` omits index bounds checks). |
| `--minify` | Minifies runtime names (such as `<obj>.runtimeType.toString()`). Enabled by default at `-O2` and higher. |
| `--[no-]strip-wasm` | Strips the static symbol `name` section from the output `.wasm` binary (enabled by default). Pass `--no-strip-wasm` for readable function names when profiling. |
| `--[no-]source-maps` | Generates a `.wasm.map` source map file alongside the `.wasm` output (enabled by default). |
| `--[no-]enable-deferred-loading` | Splits `deferred as` imports into separate `.wasm` modules loaded on demand. |
| `--standalone` | Emits a standalone `.wasm` binary without JS runtime dependencies (disallows `dart:js_interop` and `--enable-deferred-loading`). |
| `-D<key>=<value>` or `--define=<key>=<value>` | Defines compile-time environment declarations for `String.fromEnvironment`, `bool.fromEnvironment`, and `int.fromEnvironment`. |

{:.table .table-striped}

For details on compiling, optimizing, and loading Wasm applications,
refer to [WebAssembly compilation][wasm-compilation].
To learn about serving `.wasm` assets and managing source maps in production,
refer to [Web deployment][web-deployment].

[webdev]: /tools/webdev
[`webdev build`]: /tools/webdev#build
[`webdev serve`]: /tools/webdev#serve
[Dart runtime]: /overview#runtime
[wasm-compilation]: /web/wasm
[web-deployment]: /web/deployment#serving-wasm-in-production

