System Requirements for Running PI-Desktop on Linux: Complete 2024 Guide

To run PI-Desktop on Linux, you must have a 64-bit x86 system with glibc 2.35 or newer, while building from source requires Node.js 18+, pnpm, and Rust 1.70 or later.

PI-Desktop is a cross-platform Electron application distributed as AppImage, .deb, and .rpm packages. Understanding the system requirements for running PI-Desktop on Linux prevents installation failures on incompatible distributions. The repository enforces these prerequisites through startup checks in scripts/check-linux-host-glibc.mjs and build configurations that explicitly target modern toolchain versions.

Hardware and CPU Architecture Requirements

PI-Desktop only supports 64-bit x86 (x64) Linux systems. According to the release configuration in scripts/release.mjs at line 27, all Linux artifacts are compiled exclusively for the x64 architecture. The build pipeline does not generate binaries for ARM64, 32-bit x86, or other architectures.

If you attempt to run the x64 binary on an incompatible architecture, the executable will fail immediately with a format error before reaching any JavaScript or Rust code.

Runtime Library Dependencies

glibc Version Requirements (≥ 2.35)

The most critical runtime requirement is glibc version 2.35 or newer. The application performs an automatic startup check that aborts execution on older glibc versions.

As specified in packages/i18n/src/locales/en/index.ts at line 1901, the application displays a user-visible error if the host system runs Ubuntu versions older than 22.04, Debian older than 12, or Fedora older than 36. The startup script scripts/check-linux-host-glibc.mjs validates the host's glibc version before launching the Electron runtime, ensuring compatibility with the underlying Rust host-core component.

GTK and System Notification Libraries

The packaged distributions declare specific library dependencies that are automatically resolved by your package manager:

• Debian/Ubuntu (.deb): Requires libgtk-3-0 and libnotify4
• RHEL/Fedora (.rpm): Requires gtk3 and libnotify

These dependencies are defined in the Linux packaging metadata within scripts/check-linux-host-glibc.mjs and are standard for Electron applications requiring native GUI components.

Development and Build Prerequisites

Building PI-Desktop from the source repository requires three core toolchains that are not needed for running pre-built binaries.

Node.js and pnpm Requirements

The JavaScript/TypeScript build system requires Node.js 18 or newer. The CI workflow defined in .github/workflows/ci.yml at line 15 explicitly uses Node 18 for all automated builds, and the pnpm-workspace.yaml file requires pnpm as the package manager.

Install the build tooling with:

npm install -g pnpm

The workspace relies on pnpm for dependency management across the monorepo structure. Attempting to build with npm or yarn will fail due to workspace-specific configurations.

Rust Toolchain Requirements

The host-core component—the Rust backend that interfaces with AI models—must be compiled on your system using Rust 1.70 or newer (stable channel). The Cargo.toml file in the repository root pulls the latest compatible crates, requiring recent compiler features.

Ensure you have a recent stable toolchain:

rustup default stable

Electron Runtime

Pre-built packages bundle their own Electron runtime; no external Electron installation is required on the host system. The Electron configuration is managed in apps/desktop/tsconfig.json, which defines the build targets and bundling parameters for the desktop client.

Verifying System Compatibility

Before installing or building, you can manually verify glibc compatibility using the repository's check script:

# Check if your system meets the glibc 2.35 requirement

node scripts/check-linux-host-glibc.mjs ./dist/linux-unpacked/pi-desktop-host-core

This script exits with an error code and descriptive message if your glibc version is insufficient, preventing wasted time on failed builds.

Building PI-Desktop from Source

If your system meets all prerequisites, follow these steps to compile the Linux distribution:

# 1. Install required tooling

npm i -g pnpm
rustup default stable

# 2. Clone and install dependencies

git clone https://github.com/vastsa/PI-Desktop.git
cd PI-Desktop
pnpm install

# 3. Build Linux packages (AppImage, .deb, .rpm)

pnpm --filter @pi-desktop/desktop dist:linux

# 4. Launch the AppImage

./dist/PI-Desktop-1.0.0-linux-x64.AppImage

The dist:linux command internally runs the TypeScript compilation and electron-builder --linux to generate all three package formats.

Summary

• Architecture: 64-bit x86 (x64) Linux only, as defined in scripts/release.mjs
• System libraries: glibc ≥ 2.35 (Ubuntu 22.04+, Debian 12+, Fedora 36+) and GTK3/libnotify
• Build tools: Node.js ≥ 18, pnpm, and Rust ≥ 1.70 stable
• Runtime check: scripts/check-linux-host-glibc.mjs validates compatibility before launch
• Packaging: AppImage, .deb, and .rpm bundles include the Electron runtime automatically

Frequently Asked Questions

Can I run PI-Desktop on 32-bit Linux or ARM architecture?

No. The build system in scripts/release.mjs explicitly targets x64 architecture only. There are no ARM64 or 32-bit x86 build targets configured in the repository, and the Rust host-core compilation would fail on non-x64 systems due to underlying dependencies.

What happens if my glibc version is older than 2.35?

The application will refuse to start. The startup routine in scripts/check-linux-host-glibc.mjs detects the host glibc version and aborts with a localized error message stored in packages/i18n/src/locales/en/index.ts. You must upgrade to a newer distribution (Ubuntu 22.04, Debian 12, or Fedora 36) to run PI-Desktop.

Do I need to install Electron separately to run PI-Desktop?

No. Electron is bundled within the AppImage, .deb, and .rpm packages. The electron-builder configuration referenced in apps/desktop/tsconfig.json packages the runtime directly, so end users do not need Node.js or Electron installed to run the application.

Can I build PI-Desktop without Rust installed?

No. The Cargo.toml file indicates that the host-core requires native compilation. While the Electron frontend is JavaScript-based, the backend AI processing code is written in Rust and must be compiled with cargo during the build process. Rust ≥ 1.70 is mandatory for successful compilation.

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