claude-desktop-debian/docs/BUILDING.md

< Back to README

Building from Source

Prerequisites

• Linux distribution (Debian/Ubuntu, Fedora/RHEL, or other)
• Git
• Basic build tools (automatically installed by the script)

Build Instructions

# Clone the repository
git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian

# Build with auto-detected format (based on your distro)
./build.sh

# Or specify a format explicitly:
./build.sh --build deb       # Debian/Ubuntu .deb package
./build.sh --build rpm       # Fedora/RHEL .rpm package
./build.sh --build appimage  # Distribution-agnostic AppImage
./build.sh --build nix       # Nix derivation (patch only, used by flake)

# Build with custom options
./build.sh --build deb --clean no  # Keep intermediate files

# Build using a locally downloaded installer
# (useful when the bundled download URL is outdated)
./build.sh --exe /path/to/Claude-Setup.exe

The build script automatically detects your distribution and selects the appropriate package format:

Distribution	Default Format	Package Manager
Debian, Ubuntu, Mint	.deb	apt
Fedora, RHEL, CentOS	.rpm	dnf
NixOS	nix	nix
Arch Linux	.AppImage (via AUR)	yay/paru
Other	.AppImage	-

Build Environment Variables

The build pulls the Electron prebuilt binary from github.com/electron/electron/releases via @electron/get. Two upstream environment variables let you redirect that fetch:

• ELECTRON_MIRROR — base URL to fetch Electron releases from instead of GitHub. Useful for mirrors or local proxies. Example: ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/.
• ELECTRON_CUSTOM_DIR — overrides the path segment after the mirror. Defaults to v{version}.

The cache location is fixed at ~/.cache/electron/ (resolved by @electron/get via envPaths) and is reused across builds. ELECTRON_CACHE is not read by @electron/get — set ELECTRON_MIRROR if you need to avoid the public CDN.

The pinned Electron version lives in scripts/setup/dependencies.sh (electron_version) and must match build-reference/app-extracted/package.json — the upstream Claude Desktop app.asar is built against a specific Electron major and running a different one is unsupported.

Installing the Built Package

For .deb packages (Debian/Ubuntu)

sudo apt install ./claude-desktop_VERSION_ARCHITECTURE.deb
# Or: sudo dpkg -i ./claude-desktop_VERSION_ARCHITECTURE.deb

# If you encounter dependency issues:
sudo apt --fix-broken install

For .rpm packages (Fedora/RHEL)

sudo dnf install ./claude-desktop-VERSION-1.ARCH.rpm
# Or: sudo rpm -i ./claude-desktop-VERSION-1.ARCH.rpm

For AppImages

# Make executable
chmod +x ./claude-desktop-*.AppImage

# Run directly
./claude-desktop-*.AppImage

# Or integrate with your system using Gear Lever

Note: AppImage login requires proper desktop integration. Use Gear Lever or manually install the provided .desktop file to ~/.local/share/applications/.

Automatic Updates: AppImages downloaded from GitHub releases include embedded update information and work seamlessly with Gear Lever for automatic updates. Locally-built AppImages can be manually configured for updates in Gear Lever.

For NixOS

The repository includes a Nix flake. Build and install directly:

# Build the package
nix build .#claude-desktop

# Build the FHS-wrapped variant (for MCP server support)
nix build .#claude-desktop-fhs

# Run without installing
nix run .#claude-desktop

For declarative NixOS installation, see the README.

Technical Details

How It Works

Claude Desktop is an Electron application distributed for Windows. This project:

1. Downloads the official Windows installer
2. Extracts application resources
3. Replaces Windows-specific native modules with Linux-compatible implementations
4. Repackages as one of:
   • Debian package (.deb): For Debian, Ubuntu, and derivatives
   • RPM package (.rpm): For Fedora, RHEL, CentOS, and derivatives
   • AppImage: Portable, distribution-agnostic executable
   • Nix package: For NixOS, via the included flake

Build Process

The build script (build.sh) handles:

• Dependency checking and installation
• Resource extraction from Windows installer
• Icon processing for Linux desktop standards
• Native module replacement
• Package generation based on selected format

Automated Version Detection

A GitHub Actions workflow runs daily to check for new Claude Desktop releases:

1. Uses Playwright to resolve Anthropic's Cloudflare-protected download redirects
2. Compares resolved URLs with those in scripts/setup/detect-host.sh
3. If a new version is detected:
   • Updates scripts/setup/detect-host.sh with new download URLs
   • Updates nix/claude-desktop.nix with new version, URLs, and SRI hashes
   • Creates a new release tag
   • Triggers automated builds for both architectures

This ensures the repository stays up-to-date with official releases automatically.

Manual Updates

If you need to build with a specific version before the automation catches it:

1. Use a local installer: Download the latest installer from claude.ai/download and build with:

   ./build.sh --exe /path/to/Claude-Setup.exe
   

2. Update the URL: Modify the claude_download_url assignments in scripts/setup/detect-host.sh (inside the detect_architecture case statement).