Build Rustty from Source

Tip

Building Rustty from source is not recommended for most users. If you have access to a prebuilt binary or package, you should use that instead. See the binaries and packages page to see if a prebuilt binary or package is available for your platform.

If you intend to develop or package Rustty, please also check out our "Developing Rustty" and "Packaging Rustty" documents respectively. This page is more oriented towards end users who want or need to build Rustty from source for personal use.

To build Rustty, you need to first install Rust (including cargo).

Important

Each version of Rustty is only guaranteed to build with the specific Rust toolchain pinned in its rust-toolchain.toml file. Older compilers may not be able to build Rustty. If you install Rust with rustup, it reads that file automatically and provisions the pinned toolchain the first time you run cargo. If you use a distribution-provided Rust, make sure it is at least the pinned version.

The Rust version that each Rustty version requires is as follows:

Rustty version	Rust version
1.3.x	1.93.1
tip	1.93.1

Rustty also provides a Nix flake and development shell. You do not need to use Nix to build Rustty, but it is the most reproducible way to build the Linux app. See the Building with Nix section to see how to set up the Nix environment.

Depending on your platform, you may also need to install additional dependencies to build Rustty. For Linux, see Linux. For macOS, see macOS.

Begin by downloading Rustty's source tarball.

Warning

While you can compile Rustty from source by checking out its Git repository, this is not recommended for anyone but Rustty developers and contributors. This is because source tarballs contain various preprocessed files (such as a vendored dependency tree) that make Rustty require far fewer dependencies to compile and let it build offline.

If you intend to contribute to Rustty, please consult the "Developing Rustty" documents on how to build Rustty in a development environment. While most of the steps are exactly the same, we will be assuming a source tarball-based build from now on for the sake of simplicity.

For stable releases, source tarballs and their accompanying checksums can be found at rustty.sh at the following paths, where VERSION is an unprefixed version number such as 1.0.0:

https://rustty.sh/VERSION/rustty-VERSION.tar.gz
https://rustty.sh/VERSION/rustty-VERSION.tar.gz.minisig

Signature files are signed with minisign using the following public key:

RWRcF0y/6b9ncIoHA72QDYLji3/E3Yp1NiGyJyp2wVC7y0kyjfvpn7mL

For development ("tip") versions, the source tarball can be found via the tip release on GitHub, under the name rustty-source.tar.gz.

Important

The source tarball is different from GitHub's autogenerated tarball labelled "Source code (zip)" or "Source code (tar.gz)": the latter of which does not contain any preprocessed files, making it identical to a Git checkout.

Decompress the release tarball, and then navigate into the unpacked source folder:

tar -xf rustty-VERSION.tar.gz
cd rustty-VERSION/

# Or when using a tip source tarball:
# (REVISION is the commit SHA of the latest commit)

tar -xf rustty-source.tar.gz
cd rustty-VERSION-main+REVISION/

With Rust and necessary dependencies installed, a release binary can then be built using cargo build:

cargo build --release -p rustty

This builds the binary at target/release/rustty. On macOS, the app bundle is built separately; see Mac .app.

Once built, run the binary directly:

target/release/rustty

Tip

For Linux users: To install system-wide or on your user account, see Installation Directory.

Tip

For a debug build, omit the --release flag. Debug builds are extremely slow than release builds, so only use them for development.

On Linux, you'll need to install header packages for Rustty's dependencies before building it. Only a few dependencies are needed for source builds because Rustty will build everything else statically by default.

Required dependencies:

• gtk4
• libadwaita
• gtk4-layer-shell
• pkg-config or pkgconf
• gettext

Important

If you're using a Git checkout, you also need to install these dependencies:

• blueprint-compiler (version 0.16.0 or newer)

Tip

If your distro has yet to package gtk4-layer-shell (e.g. Ubuntu 24.04, Debian 12, Linux Mint 22.1, OpenSUSE, etc.), you need to build and install gtk4-layer-shell from source yourself. Rustty links it through pkg-config and, unlike Rustty, has no vendored copy or -fno-sys flag.

doas apk add \
  gtk4.0-dev \
  libadwaita-dev \
  pkgconf \
  ncurses \
  gettext

sudo pacman -S \
  gtk4 \
  gtk4-layer-shell \
  pkgconf \
  libadwaita \
  gettext

sudo apt install \
  libgtk-4-dev \
  libgtk4-layer-shell-dev \
  libadwaita-1-dev \
  gettext \
  libxml2-utils

On Debian unstable/testing, the gcc-multilib package is also required for building.

On Fedora variants, use

sudo dnf install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  gettext

On Fedora Atomic variants, use

rpm-ostree install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  gettext

emerge -av \
  libadwaita \
  gtk \
  blueprint-compiler \
  gettext

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  gettext \
  gtk4-layer-shell-devel

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  gettext

sudo eopkg install \
  libgtk-4-devel \
  libadwaita-devel \
  pkgconf \
  gettext

sudo xbps-install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  pkg-config \
  gettext

Cargo does not install into a prefix itself. Instead, build the release binary and then use xtask to generate the runtime resources (terminfo, shell integration, themes, man pages, desktop files, icons, etc.) and copy both into a target directory. This sets up the proper FHS directory structure that ensures features such as shell integration, icons, GTK shortcuts, etc. all work.

For local, unprivileged installs, we recommend $HOME/.local:

cargo build --release -p rustty
install -Dm755 target/release/rustty $HOME/.local/bin/rustty
cargo run -p xtask -- resources --target-os linux --prefix $HOME/.local
cp -R zig-out/share/. $HOME/.local/share/

With a typical Freedesktop-compatible desktop environment (i.e. GNOME, KDE), this will make Rustty available as an app in your app launcher. If you don't see it immediately you may have to log out and log back in or maybe even restart.

If Rustty fails to launch using an app icon in your app launcher, ensure that ~/.local/bin is on your system PATH. The desktop environment itself must have that path in the PATH. Google for your specific desktop environment and distribution to learn how to do that.

For system-wide installs, we recommend /usr (likely requires sudo):

cargo build --release -p rustty
sudo install -Dm755 target/release/rustty /usr/bin/rustty
cargo run -p xtask -- resources --target-os linux --prefix /usr
sudo cp -R zig-out/share/. /usr/share/

The Nix build environment can be accessed like any other Nix dev shell, via the nix develop command (or nix-shell if you don't have the nix-command experimental feature enabled).

If you use nix-direnv, Rustty provides an .envrc file you can source by running direnv allow. This will allow you to seamlessly enter and exit the Rustty development environment as you enter and exit the Rustty repository. Direnv is not required.

After setting up the Nix environment, you can run the same cargo build as on other distributions or you can also build the package with Nix by running:

nix build .#rustty

The binary would then be located under ./result/bin/rustty. This package is Linux-only; the headless VT library is available as nix build .#librustty-vt.

Building with Nix should yield the same result as building it with Cargo, but with higher reproducibility guarantees that ensure every part of Rustty can be built reliably.

To build the macOS application, you must build on a macOS machine with Xcode installed and the active developer directory pointing to it. If you're not sure that's the case, check the output of xcode-select --print-path:

xcode-select --print-path
/Library/Developer/CommandLineTools        # <-- BAD

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcode-select --print-path
/Applications/Xcode.app/Contents/Developer # <-- GOOD

The above can happen if you install the Xcode Command Line Tools after Xcode is installed.

Next, make sure you have the macOS SDK, iOS SDK, and Metal Toolchain installed (from inside Xcode → Settings → Components). Main branch development of Rustty requires Xcode 26 and the macOS 26 SDK.

Because the build uses rustup to add the aarch64-apple-darwin and x86_64-apple-darwin targets for a universal binary, make sure rustup is installed.

No additional library dependencies (such as Homebrew's gettext) are needed: Rustty builds its own copies and links them into the app.

CONFIGURATION=ReleaseLocal macos/build-rustty.sh

This packages the RusttyKit.xcframework, generates the app's resources, and builds the app with xcodebuild. It outputs the app to zig-out/Rustty.app.

The app created will use the "ReleaseLocal" Xcode build configuration. The "ReleaseLocal" build configuration is specifically for local release builds and disables some security features (such as "Library Validation") to make it easier to run without having to have a code signing identity and so on. These builds aren't meant for distribution. If you want a release build with all security features, use the official binary build.