Install the compiler

The fast path: install a pre-built axle binary from the project’s apt repository (Debian / Ubuntu) or its Windows MSI, or build the container below and run axle inside it. If you want to hack on the compiler itself, see Build the compiler instead.

This page covers:

the apt repository setup, and what apt pulls in alongside axle;
the Windows MSI, and what to do on macOS or arm64 Linux;
a Dockerfile for a reproducible Linux environment;
the CLI subcommand surface and the two flags worth knowing early.

Debian / Ubuntu (apt)

The repository setup is scripted:

curl -fsSL https://axle-lang.dev/install.sh | sh

or done by hand:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.axle-lang.dev/key.asc \
    | sudo gpg --dearmor -o /etc/apt/keyrings/axle.gpg
echo "deb [signed-by=/etc/apt/keyrings/axle.gpg arch=amd64] https://apt.axle-lang.dev stable main" \
    | sudo tee /etc/apt/sources.list.d/axle.list
sudo apt update
sudo apt install axle
axle --help

Pulls the latest axle package (the compiler driver) plus the two tools it drives at link time: an LLD alternative (lld, lld-21, lld-17 … lld-14) and a C driver (gcc or clang). LLVM itself is not installed — the compiler links it into the binary, so no llvm-* package is needed.

Updates land via plain sudo apt upgrade once the repository is configured.

Docker

A reproducible single-image build that bundles the same apt install above:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates curl gnupg lld-21 \
    && rm -rf /var/lib/apt/lists/*

RUN install -m 0755 -d /etc/apt/keyrings \
 && curl -fsSL https://apt.axle-lang.dev/key.asc \
      | gpg --dearmor -o /etc/apt/keyrings/axle.gpg \
 && echo "deb [signed-by=/etc/apt/keyrings/axle.gpg arch=amd64] https://apt.axle-lang.dev stable main" \
      > /etc/apt/sources.list.d/axle.list \
 && apt-get update \
 && apt-get install -y hyperfine time \
 && apt-get install -y axle \
 && rm -rf /var/lib/apt/lists/* \
 && axle --version

WORKDIR /work
ENTRYPOINT ["axle"]
CMD ["--version"]

Build + use it:

docker build -t axle .
docker run --rm -v "$PWD":/work axle build hello.axle -o hello

The hyperfine and time packages are pre-installed so you can benchmark from inside the container without rebuilding the image.

Windows

The release pipeline publishes an x86_64 MSI — the compiler, the language server, and the runtime static libraries — from the download page:

https://dl.axle-lang.dev/latest/axle-windows-x86_64.msi

The installer is unsigned, so SmartScreen warns on first run.

macOS and arm64 Linux

There is no native package on either. The apt repository is x86-64 Linux and no macOS artefact is published. Two options:

Docker — the Dockerfile above; the --rm -v "$PWD":/work invocation works identically on Docker Desktop / Colima.
Build from source — follow Build the compiler, which pins the Rust toolchain and LLVM 21 the compiler needs.

CLI subcommands

axle new    <name>          Create a new project (manifest + src/main.axle);
                            --lib scaffolds a library, --workspace a
                            multi-crate workspace (the two are exclusive)
axle build  [input]         Compile a file or project to a native binary
axle run    [input]         Compile + run a file or project
axle check  [input]         Type-check only, no binary produced.
                            A directory (or nothing) checks that project;
                            --target checks another platform's port.
axle ports  [dir]           List a project's ports, its seams, and what
                            each port still owes (--target to switch)
axle fmt    [files]         Format .axle sources in place (--check to verify)
axle bench  <input>         Compile + benchmark (with --compare cpp,rust)
axle profile [input]        Run the program and report where its time went

axle <subcommand> --help shows every option. The build subcommand notably accepts --emit {binary,llvm,llvm-raw,bitcode,asm,object,hir,ast,header}, -O 0..3, and --target <triple> for cross-compilation. object and header are the pair that make a library something C can link against — see Exporting to C.

A binary build lowers the program into several object files and builds them concurrently, sized from the program and the machine’s core count. --codegen-units N pins that number; 1 is the single-module build, which is what to compile at when the question is whether the split is responsible for something. Only the binary path splits — every other --emit produces one file and one module.

The optimisation levels are not a single LLVM dial: -O 0 runs nothing at all — neither the HIR transforms nor the LLVM pipeline — and is the level to compile at when the question is whether an optimisation is responsible for something. -O 1 (the default) runs every HIR transform with no LLVM pipeline behind it; -O 2 and -O 3 add LLVM’s own.

axle run builds a native binary and executes it, on a bare .axle file as inside a project directory; axle build is the same build with the binary kept.

Limitations

The apt repository serves x86-64 Linux only. Its sources line is pinned to arch=amd64. arm64 Linux and macOS have no native package: use the Dockerfile above or build from source. Windows gets its x86_64 MSI from the download page, not apt.
There is no published image to run. The project pushes one image to a registry — its pinned CI base, not a distribution of the compiler. The Dockerfile above is for you to docker build; there is nothing to docker pull.

What’s next

Write your first program — Hello, Axle.
Wire up your editor — Editor support covers the VS Code extension and how to drive axle-lsp from other LSP-aware editors.
Browse the Language tour.
When you need a specific stdlib symbol, see the API reference.