How to Build Claude Desktop Debian Packages from a Windows Installer

You can convert the official Claude Desktop Windows installer into a native .deb package by extracting the Electron app with 7-Zip, patching Windows-specific modules for Linux compatibility, and repackaging it using the build scripts in the aaddrick/claude-desktop-debian repository.

Claude Desktop is officially distributed only as a Windows .exe installer, but the open-source aaddrick/claude-desktop-debian project automates the process of repackaging it for Debian-based Linux distributions. The build pipeline downloads the Windows installer, extracts the underlying Electron application, replaces native Windows modules with Linux-compatible stubs, and generates a standard .deb package that integrates with your desktop environment.

How the Build Process Works

The conversion process follows a four-stage pipeline orchestrated by build.sh:

1. Download and extraction: The script fetches the official Windows installer (or accepts a local file) and extracts it using 7z to locate the .nupkg containing the Electron app and app.asar archive.

2. Patching: Windows-specific native modules—such as node-pty, the cowork-VM service, and frame-management components—are replaced with Linux-compatible wrappers and stubs defined in the patch_* functions within build.sh.

3. Staging: The patched application is assembled into a standard Linux directory layout under /usr/lib/claude-desktop, including icons, desktop entries, and wrapper scripts.

4. Packaging: The scripts/build-deb-package.sh utility creates the Debian control files, writes the DEBIAN/control metadata, and invokes dpkg-deb --build to produce the final .deb artifact.

Prerequisites

Before building, ensure your system has the following dependencies installed:

• Git to clone the repository
• 7-Zip (p7zip-full package) for extracting the Windows installer
• Electron and Node.js tooling (handled automatically by the script)
• Standard build tools (dpkg-deb for Debian systems)

sudo apt update
sudo apt install -y git p7zip-full dpkg-dev

Step-by-Step Build Instructions

1. Clone the Repository

git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian

2. (Optional) Download the Windows Installer

If the auto-download URL in build.sh is outdated or you need a specific version, manually download the Windows installer:

wget -O Claude-Setup.exe https://claude.ai/download

3. Build the Debian Package

To build from a local installer file, specify the --exe flag and target format:

./build.sh --build deb --exe ./Claude-Setup.exe

The script performs the following actions defined in build.sh:

• Sets local_exe_path from the --exe argument
• Copies the file to work_dir/Claude-Setup.exe
• Skips download_claude_installer per the conditional logic
• Proceeds through extraction (7z x), patching, and delegates to scripts/build-deb-package.sh

4. Install the Package

Once complete, the .deb file appears in the build/ directory:

sudo apt install ./build/claude-desktop_<version>_<arch>.deb

To keep intermediate files for debugging (useful if patching fails), add the --clean no flag:

./build.sh --build deb --clean no --exe ./Claude-Setup.exe

Understanding the Patching Process

The build.sh script contains multiple patch_* functions that modify the extracted Electron application to function on Linux:

• Frame fixing: The frame-fix-wrapper.js and associated logic replace Windows-specific window frame management with Linux-compatible alternatives.
• PTY replacement: The node-pty module, which handles terminal emulation, is patched to use Linux native bindings instead of Windows conpty.
• CoWork VM service: Windows-specific virtualization hooks are stubbed out or redirected to Linux equivalents.
• Protocol handling: Custom URL scheme handlers are adjusted for Linux desktop integration.

These patches are applied after the 7z extraction locates the .nupkg and app.asar files, but before scripts/build-deb-package.sh assembles the final directory structure.

Summary

Building Claude Desktop Debian packages from the Windows installer requires:

• Extracting the Windows .exe using 7z to access the embedded .nupkg and app.asar
• Patching native Windows modules (node-pty, frame management, VM services) using the patch_* functions in build.sh
• Repackaging via scripts/build-deb-package.sh, which creates the DEBIAN control structure and runs dpkg-deb --build
• Installing the resulting .deb from the build/ directory using apt

The ./build.sh --build deb --exe <path> command automates the entire pipeline, handling extraction, patching, and packaging in a single invocation.

Frequently Asked Questions

Can I build the Debian package without downloading the Windows installer manually?

Yes. If you omit the --exe flag, build.sh automatically downloads the latest Windows installer using the CLAUDE_DOWNLOAD_URL defined for your architecture. However, providing a local file with --exe ensures you can build when the auto-download URL is outdated or when working offline.

What architectures are supported for the Debian build?

The build.sh script supports amd64 (x86_64) and arm64 architectures. The download URL and build process automatically adjust based on the host architecture detected during execution, though you can manually specify target parameters by modifying the script variables.

Why does the build process need to patch node-pty and other native modules?

Claude Desktop is built for Windows and includes native Node.js modules like node-pty that rely on Windows-specific APIs (such as Windows ConPTY). When extracting the Windows installer, these modules must be replaced with Linux-compatible versions or stubs via the patch_* functions in build.sh to ensure the terminal integration and window management work correctly on Debian systems.

Where is the final .deb file located after the build completes?

The scripts/build-deb-package.sh script places the finished package in the build/ directory at the repository root. The filename follows the standard Debian convention: claude-desktop_<version>_<arch>.deb (for example, claude-desktop_0.7.7_amd64.deb).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}