How to build the Cutefish desktop from source and install it on an existing Linux distribution.
This guide is written for people trying Cutefish early and for AI coding agents doing the build for them. Commands are complete and run in order; an agent can follow them step by step.
Cutefish is developed and tested on Debian 13 (trixie). Other distributions work if they ship the library versions listed under Requirements; the package names below are Debian’s, and Other distributions explains how to find the equivalents.
Components
| Repository | Need | What it is |
|---|---|---|
| cutefish-toolkit | Required | UI toolkit every component is built on |
| cutefish-framework | Required | Clients of system services, file operations, PDF documents |
| cutefish-core | Required | Session, system services, polkit agent, screen recorder |
| cutefish-compositor | Required | Wayland compositor, window manager, menu bar, dock, launcher, lock screen |
| filemanager | Required | File manager; also draws the desktop and its icons |
| icons | Required | Default icon theme |
| wallpapers | Required | Default wallpaper |
| settings | Recommended | System Settings |
| terminal | Recommended | Terminal |
| xdg-desktop-portal-cutefish | Recommended | File chooser, screen sharing and settings for sandboxed and browser apps |
| cutefish-dm | Optional | Login screen; skip it if you keep SDDM, GDM or LightDM |
| qt-plugins | Optional | Qt 6 apps follow dark mode, system fonts and icons, open the Cutefish file chooser, and scroll like Cutefish apps |
| text-editor | Optional | Text editor |
| video-player | Optional | Video player |
| calendar | Optional | Calendar |
| calculator | Optional | Calculator |
| preview | Optional | Image and PDF viewer |
| system-monitor | Optional | System monitor |
| cutefish-computer-use | Optional | MCP server that lets agents such as Claude Code and Codex see and use the desktop, with your permission |
Without the recommended components the desktop runs, but the Settings and Terminal icons pinned to the dock open nothing.
Requirements
- A GPU with an EGL and OpenGL ES 2 driver and kernel modesetting. Virtual machines need a 3D-capable display device, such as virtio-gpu with virgl.
- systemd and systemd-logind.
- Wayland 1.23 or newer, wayland-protocols 1.39 or newer, PipeWire 0.3.65 or newer, CMake 3.22 or newer.
- A C++20 compiler (GCC or Clang) and Clang, which builds Skia.
- Network access before building, to download Skia for cutefish-toolkit, PDFium for cutefish-framework, and libghostty-vt with the Zig compiler that builds it for terminal.
- Optional components: Qt 6 for qt-plugins, libmpv 0.35 or newer for video-player, Rust and Cargo for cutefish-computer-use.
- gettext’s
msgfmtfor the translations. Without it everything still builds, in English only.
Everything installs into /usr. Use -DCMAKE_INSTALL_PREFIX=/usr as shown;
other prefixes do not work, because the session and the compositor start
and trust their programs by their /usr/bin paths.
1. Install the build dependencies
On Debian 13, for the required and recommended components:
sudo apt update
sudo apt install git cmake ninja-build pkg-config clang python3 gettext curl minisign \
libwayland-dev libwayland-bin wayland-protocols \
libegl-dev libgles-dev libgbm-dev libdrm-dev \
libxkbcommon-dev libinput-dev libseat-dev libudev-dev libsystemd-dev libpam0g-dev \
libfontconfig-dev libfreetype-dev libharfbuzz-dev libicu-dev libexpat1-dev \
libpng-dev libjpeg-dev zlib1g-dev libwebp-dev libtiff-dev libheif-dev libjxl-dev \
liblcms2-dev libopenjp2-7-dev libhwy-dev libabsl-dev \
libpipewire-0.3-dev libspa-0.2-dev \
libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libva-dev \
libxcb1-dev libxcb-composite0-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-sync-dev \
libarchive-dev libfuse3-dev libmtp-dev libsmbclient-dev libssh-dev libzip-dev \
libcrypt-dev libxcursor-dev libpcre2-dev gtk-update-icon-cache
Add these for the optional components you want:
| Component | Packages |
|---|---|
| cutefish-dm | none beyond the list above |
| qt-plugins | qt6-base-dev qt6-base-private-dev qt6-declarative-dev qt6-declarative-private-dev librsvg2-dev |
| text-editor | none beyond the list above |
| video-player | libmpv-dev |
| calendar | libcurl4-openssl-dev libical-dev |
| calculator | none beyond the list above |
| preview | none beyond the list above |
| system-monitor | none beyond the list above |
| cutefish-computer-use | rustc cargo librust-wayland-client-dev librust-wayland-scanner-dev librust-wayland-protocols-dev librust-wayland-backend-dev librust-serde-json-dev librust-png-dev librust-jpeg-encoder-dev librust-base64-dev librust-bitflags-dev librust-libc-dev librust-memmap2-dev |
To build the tests as well, add libgtest-dev and configure with
-DBUILD_TESTING=ON instead of OFF in step 3.
2. Get the sources
Clone the repositories side by side. Leave out the optional ones you do not want.
mkdir -p ~/cutefish && cd ~/cutefish
for repo in cutefish-toolkit cutefish-framework cutefish-core cutefish-compositor \
filemanager icons wallpapers settings terminal xdg-desktop-portal-cutefish \
cutefish-dm qt-plugins text-editor video-player calendar calculator preview \
system-monitor cutefish-computer-use; do
git clone https://github.com/cutefishos/$repo.git
done
cutefish-toolkit builds a pinned revision of Skia and cutefish-framework a pinned revision of PDFium, which have to be fetched first:
cutefish-toolkit/scripts/fetch-skia.sh
cutefish-framework/scripts/fetch-pdfium.sh
3. Build and install
terminal links libghostty-vt
1.0 statically, found as the pkg-config module cutefish-ghostty-vt. Build
it first, with the Zig 0.17 release it needs; both downloads are checked
against their publishers’ minisign keys. Skip this if you leave out
terminal.
mkdir -p ~/cutefish/ghostty-vt && cd ~/cutefish/ghostty-vt
zig=zig-$(uname -m)-linux-0.17.1
curl -fsSLO https://ziglang.org/download/0.17.1/$zig.tar.xz
curl -fsSLO https://ziglang.org/download/0.17.1/$zig.tar.xz.minisig
minisign -Vm $zig.tar.xz -P RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U
tar -xJf $zig.tar.xz
base=https://release.files.ghostty.org/libghostty-vt/1.0.1
for f in libghostty-vt-1.0.1.tar.gz libghostty-vt-1.0.1-deps.tar.gz; do
curl -fsSLO $base/$f
curl -fsSLO $base/$f.minisig
minisign -Vm $f -P RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV
tar -xzf $f
done
cd libghostty-vt-1.0.1
DESTDIR=~/cutefish/ghostty-vt/stage ../$zig/zig build --prefix /usr \
--prefix-lib-dir lib/cutefish-ghostty-vt --prefix-include-dir include/cutefish-ghostty-vt \
--system ../libghostty-vt-1.0.1-deps -Doptimize=ReleaseFast
Install only the static library, the headers and a pkg-config file of Cutefish’s own, so nothing of it is needed at run time and a distribution’s libghostty-vt can sit beside it:
cd ~/cutefish/ghostty-vt/stage/usr
sudo install -Dm644 -t /usr/lib/cutefish-ghostty-vt lib/cutefish-ghostty-vt/libghostty-vt.a
sudo cp -r include/cutefish-ghostty-vt /usr/include/
sudo install -d /usr/share/pkgconfig
sudo tee /usr/share/pkgconfig/cutefish-ghostty-vt.pc > /dev/null << 'EOF'
libdir=/usr/lib/cutefish-ghostty-vt
includedir=/usr/include/cutefish-ghostty-vt
Name: cutefish-ghostty-vt
Description: libghostty-vt, static, for building Cutefish
Version: 1.0.1
Cflags: -I${includedir} -DGHOSTTY_STATIC
Libs: -L${libdir} -lghostty-vt -lm
EOF
pkg-config --modversion cutefish-ghostty-vt
The last command prints 1.0.1.
Then build the projects in this order. Each project is installed before the next is configured, because later projects find earlier ones through their installed CMake packages.
cd ~/cutefish
for repo in cutefish-toolkit cutefish-framework qt-plugins icons cutefish-core \
cutefish-dm filemanager terminal xdg-desktop-portal-cutefish settings \
system-monitor text-editor video-player calendar calculator preview \
cutefish-compositor wallpapers; do
[ -d "$repo" ] || continue
cmake -S "$repo" -B "build/$repo" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTING=OFF || break
cmake --build "build/$repo" --parallel "$(nproc)" || break
sudo cmake --install "build/$repo" || break
done
The loop stops at the first failure; fix it, usually a missing package, and run it again. cutefish-toolkit takes the longest, since it builds Skia.
cutefish-computer-use is built with Cargo instead:
cd ~/cutefish/cutefish-computer-use
cargo build --release
sudo install target/release/cutefish-computer-use /usr/bin/
To let an agent use it, see Letting agents use the desktop.
To build the compositor without X11 application support, which also drops
the libxcb-* build dependencies, configure it with
-DCUTEFISH_ENABLE_XWAYLAND=OFF.
4. Install the runtime dependencies
sudo apt install accountsservice polkitd gsettings-desktop-schemas xdg-user-dirs locales \
network-manager bluez upower power-profiles-daemon udisks2 fuse3 \
pipewire pipewire-pulse wireplumber gnome-keyring libpam-gnome-keyring \
xdg-desktop-portal xwayland adwaita-icon-theme
xwayland runs X11 applications; adwaita-icon-theme provides the fallback
cursors; locales lets Cutefish generate the locale of a language picked in
Settings, so its dates and numbers follow it too. systemd-coredump is recommended, so the crash dialog can show
what crashed.
5. Log in
With your existing display manager
Log out, choose Cutefish (Wayland) in the session menu of SDDM, GDM or LightDM, and log in. Nothing else is needed; cutefish-dm can stay uninstalled.
With cutefish-dm (optional)
cutefish-dm runs its login screen as a system user, which a source install has to create once:
sudo useradd --system --user-group --home-dir /var/lib/cutefish-greeter \
--create-home cutefish-greeter
Then replace the current display manager. This takes effect at the next
boot; replace sddm with gdm3 or lightdm as appropriate.
sudo systemctl disable sddm
sudo systemctl enable cutefish-dm
To go back, run the same commands with the names swapped.
Updating
Pull every repository, fetch Skia and PDFium again in case their pinned revisions changed, and run the loop in step 3 again, along with the Cargo build of cutefish-computer-use if you have it:
cd ~/cutefish
for repo in */; do [ -d "$repo/.git" ] && git -C "$repo" pull --ff-only; done
cutefish-toolkit/scripts/fetch-skia.sh
cutefish-framework/scripts/fetch-pdfium.sh
libghostty-vt needs rebuilding only when terminal’s README asks for a newer version.
Log out and back in afterwards. The file manager also draws the desktop, so a new filemanager build takes effect at the next login.
Uninstalling
Each build directory records what it installed:
cd ~/cutefish
for manifest in build/*/install_manifest.txt; do
xargs -d '\n' sudo rm -f -- < "$manifest"
done
sudo rm -f /usr/bin/cutefish-computer-use
sudo rm -rf /usr/lib/cutefish-ghostty-vt /usr/include/cutefish-ghostty-vt \
/usr/share/pkgconfig/cutefish-ghostty-vt.pc
Switch back to your previous display manager first if you enabled cutefish-dm.
Other distributions
Build dependencies are looked up through pkg-config, apart from a few
libraries found by name, noted in the table. Install the package that
provides each module below; on Fedora, sudo dnf install 'pkgconfig(<module>)' does this directly, and on Arch Linux,
pacman -F <module>.pc names the package.
| Components | pkg-config modules |
|---|---|
| All | wayland-client (>= 1.23), wayland-server, wayland-egl, wayland-scanner, wayland-protocols (>= 1.39), egl, glesv2, xkbcommon, libsystemd, fontconfig, freetype2, harfbuzz, icu-uc, icu-i18n, expat, libpng, libjpeg, zlib, libwebp, libtiff-4, libheif, libjxl, libjxl_threads |
| cutefish-framework | libpipewire-0.3 (>= 0.3.65), libspa-0.2, harfbuzz-subset, lcms2, libopenjp2, libhwy, absl_flat_hash_set, absl_inlined_vector, absl_cleanup |
| cutefish-core | gbm, libdrm, libavcodec, libavformat, libavutil, libswscale, libva |
| cutefish-compositor | gbm, libdrm, libinput, libseat, libudev, xcb, xcb-composite, xcb-xfixes, xcb-shape, xcb-sync; the PAM library |
| cutefish-dm | the PAM library |
| filemanager | libarchive, fuse3, libmtp, smbclient, libssh, libudev, and the libzip headers and library |
| settings | xcursor; the libcrypt library |
| terminal | libpcre2-8; cutefish-ghostty-vt, built in step 3 |
| text-editor | libpcre2-8 |
| video-player | mpv (>= 2.0, from libmpv 0.35) |
| calendar | libcurl, libical |
| qt-plugins | Qt 6 Core, Gui, Widgets, DBus, Quick and their private headers; librsvg-2.0 |
cutefish-computer-use’s .cargo/config.toml builds offline against Debian’s
packaged crates in /usr/share/cargo/registry. Elsewhere, delete that file
and Cargo fetches the same crates from crates.io.
Besides libraries, the build needs git, cmake, ninja, pkg-config,
clang, python3, gettext (for translations), gtk-update-icon-cache
(for icons), and curl and minisign (for libghostty-vt). Use the Zig
release step 3 downloads rather than a distribution’s Zig, since
libghostty-vt 1.0 needs Zig 0.17. The runtime services in step 4 go by the same names on most
distributions:
NetworkManager, BlueZ, UPower, power-profiles-daemon, UDisks2, PipeWire with
WirePlumber, AccountsService, polkit, GNOME Keyring, xdg-desktop-portal and
Xwayland.