Installing buildctl¶

From source¶

Prerequisites¶

• Go 1.22 or later
• Git

Build¶

git clone https://github.com/offline-lab/buildctl.git
cd buildctl
make build

The binary is at build/bin/buildctl. Copy it to your PATH:

cp build/bin/buildctl /usr/local/bin/

Cross-compile¶

make cross-compile
# Binaries in build/bin/:
#   buildctl-linux-amd64
#   buildctl-linux-arm64
#   buildctl-darwin-amd64
#   buildctl-darwin-arm64

From Homebrew (macOS)¶

brew tap offline-lab/tap
brew install buildctl

From package manager (Linux)¶

Debian/Ubuntu¶

# Download the latest .deb from the GitHub Releases page
sudo dpkg -i buildctl_<version>_linux_amd64.deb

Fedora/RHEL¶

# Download the latest .rpm from the GitHub Releases page
sudo rpm -i buildctl-<version>-1.x86_64.rpm

From GitHub Releases¶

Download the appropriate archive for your platform from GitHub Releases, extract it, and add the binary to your PATH.

# Example: macOS ARM64
curl -L https://github.com/offline-lab/buildctl/releases/latest/download/buildctl_macOS-arm64.tar.gz | tar xz
sudo mv buildctl /usr/local/bin/

Verify the download against the published checksums before running.

Verify installation¶

buildctl version
# buildctl <version> (commit: <hash>, built: <date>)

Docker setup¶

For cross-architecture builds via the Docker backend, run once:

buildctl init

This ensures the buildctl-builder buildx builder exists and registers QEMU binfmt handlers for cross-architecture emulation (arm64, armv7, etc.). On macOS, Docker Desktop provides binfmt natively; on Linux, init installs the handlers via a privileged container. See Cross-compile for a different architecture.

Backend dependencies¶

buildctl auto-detects the build backend from the project directory. See Build backends for the contract and per-backend details.

Next steps¶

• Build your first package: end-to-end walkthrough.
• Command reference: every command and flag.