THIS IS AN UNOFFICIAL BUILD SCRIPT!
If you run into an issue with this build script, make an issue here. Don't bug Anthropic about it - they already have enough on their plates.
Supports MCP!
Supports the Ctrl+Alt+Space popup! (natively on Wayland via the XDG global-shortcuts portal on GNOME 48+/KDE — see Display backend & global shortcuts)
Supports the Tray menu! (Screenshot of running on KDE)
This is a Nix flake for running Claude Desktop on Linux with proper desktop integration.
To run this once, make sure Nix is installed, then run
NIXPKGS_ALLOW_UNFREE=1 nix run github:k3d3/claude-desktop-linux-flake --impureThe "unfree" part is due to the fact that Claude Desktop is not an open source application, and thus, Nix's licensing rules are dictated by the application itself, not the build script used to build the application.
Add the following to your flake.nix:
inputs.claude-desktop.url = "github:k3d3/claude-desktop-linux-flake";
inputs.claude-desktop.inputs.nixpkgs.follows = "nixpkgs";
inputs.claude-desktop.inputs.flake-utils.follows = "flake-utils";And then the following package to your environment.systemPackages or home.packages:
inputs.claude-desktop.packages.${system}.claude-desktopIf you would like to run MCP servers with Claude Desktop on NixOS, use the claude-desktop-with-fhs package. This will allow running MCP servers with calls to npx, uvx, or docker (assuming docker is installed).
inputs.claude-desktop.packages.${system}.claude-desktop-with-fhsThis flake includes comprehensive fixes for proper GNOME desktop integration, particularly on Wayland:
- Correct Icon Display: Shows the proper orange Claude sunburst icon instead of a generic gear icon
- Dock Icon Grouping: Running applications properly group with pinned dock icons (no duplicate icons)
- Wayland Compatibility: Proper window class and desktop file association for GNOME on Wayland
- FHS + Desktop Integration: The
claude-desktop-with-fhspackage includes both MCP server support AND desktop files
The integration has been thoroughly tested on GNOME 48 with Wayland and works reliably across different installation methods.
The launcher defaults to native Wayland via --ozone-platform-hint=auto. On a
Wayland session it runs natively on Wayland; on an X11 session it transparently
falls back to X11, so the default is safe either way.
Quick Entry's global shortcut (Ctrl+Alt+Space) works under native Wayland by
routing through the XDG GlobalShortcuts portal. That path requires
xdg-desktop-portal with a GlobalShortcuts backend:
- GNOME 48+ and KDE Plasma ship one. On GNOME a one-time permission dialog appears the first time the shortcut is bound — approve it for the hotkey to work.
- Compositors whose portal has no GlobalShortcuts backend (e.g. most wlroots setups like Sway/Hyprland) silently make the feature a no-op — the global hotkey won't fire under native Wayland there.
If the portal route misbehaves on your compositor, set CLAUDE_USE_X11=1 to
force XWayland. That restores the older X11 key-grab global shortcut and the more
mature IME/HiDPI rendering path.
| Variable | Default | Effect |
|---|---|---|
CLAUDE_USE_X11 |
unset | Set to 1 to force XWayland (--ozone-platform=x11) instead of native Wayland. |
GTK_USE_PORTAL |
1 |
Use the XDG portal for native file dialogs. Set to 0 to use Electron's built-in GTK dialogs. |
GTK_THEME |
Adwaita:dark |
Passed through to the app; override to change theming. |
COLOR_SCHEME_PREFERENCE |
dark |
Light/dark preference hint. |
This repository only provides a Nix flake, and does not provide a package for e.g. Ubuntu, Fedora, or Arch Linux.
Other known variants:
- https://github.com/aaddrick/claude-desktop-debian - A debian builder for Claude Desktop
- https://aur.archlinux.org/packages/claude-desktop-bin - An Arch package for Claude Desktop
- https://github.com/wankdanker/claude-desktop-linux-bash - A bash-based Claude Desktop builder that works on Ubuntu and possibly other Debian derivatives
If anyone else packages Claude Desktop for other distributions, make an issue or PR and I'll link it here.
Claude Desktop is an Electron application. That means the majority of the application is inside an app.asar archive, which usually contains minified Javascript, HTML, and CSS, along with images and a few other things.
Despite there being no official Linux Claude Desktop release, the vast majority of the code is completely cross-platform.
With the exception of one library.
Node, and by extension Electron, allow you to import natively-compiled objects into the Node runtime as if they were regular modules. These are typically used to extend the functionality in ways Node itself can't do. Only problem, as shown above, is that these objects are only compiled for one OS.
Luckily enough, because it's a loadable Node module, that means you can open it up yourself in node and inspect it - no decompilation or disassembly needed:
There are many functions here for getting monitor/window information, as well as for controlling the mouse and keyboard. I'm not sure what exactly these are for - my best guess is something unreleased related to Computer Use, however I'm not a huge fan of this functionality existing in the first place.
As for how to move forward with getting Claude Desktop working on Linux, seeing as how the API surface area of this module is relatively small, it looked fairly easy to just wholesale reimplement it, using stubs for the functionality.
The result of that is a library I call patchy-cnb, which uses NAPI-RS to match the original API with stub functions.
Turns out, the original module also used NAPI-RS. Neat!
From there, it's just a matter of compiling patchy-cnb, repackaging the app.asar to include the newly built Linux module, and
making a new Electron build with these files.
This is a repackaging of a macOS build, and a few things either don't work or work differently than on macOS. Rather than pretend otherwise:
patchy-cnbis a stub. The Windows/macOSclaude-nativemodule is reimplemented as no-ops: window/monitor enumeration returns empty, and the mouse/keyboard control entry points do nothing. Anything that would drive Computer Use-style screen/input control through these native bindings is therefore inert. The normal chat app does not depend on them, so day-to-day use is unaffected.- Cowork / local-agent native features are not wired up. This flake does not vendor the Cowork daemon, bubblewrap/KVM sandbox backends, or
node-ptythat the aaddrick/claude-desktop-debian build ships. Features that depend on the Cowork VM service won't be available here. If you need those, that project (which also offers a Nix flake) is the more complete option today. - In-app auto-update is intentionally disabled. On Nix the store path is read-only, so the app can't update itself. Updates are this repo's job instead: the weekly
update-claude-desktopworkflow reads Claude'sRELEASES.json, repins the flake, and opens an auto-merging PR once a realnix build(including patch verification) passes. Bump your flake input to get the new version. - Native Wayland global shortcuts depend on your compositor's portal. See Display backend & global shortcuts — they work on GNOME 48+/KDE but are a no-op on portals without a GlobalShortcuts backend; use
CLAUDE_USE_X11=1there.
The build scripts in this repository, as well as patchy-cnb, are dual-licensed under the terms of the MIT license and the Apache License (Version 2.0).
See LICENSE-MIT and LICENSE-APACHE for details.
The Claude Desktop application, not included in this repository, is likely covered by Anthropic's Consumer Terms.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.