# Install Pieces on Linux

Install Pieces on Linux with Flatpak or Snap. Step-by-step setup for PiecesOS and the Pieces Desktop App on Fedora, Arch, Debian, Ubuntu, Linux Mint, and more.

## Install Pieces on Linux

Pick how you'd like to install Pieces. Flatpak is recommended for most
distributions; Snap is a good fit for Ubuntu. Expand a method below for
step-by-step setup of both PiecesOS and the Desktop App.

## Flatpak (recommended)

Works across most distributions — Fedora, Arch, Debian, Ubuntu, Linux Mint, and more.

[Requirements, updating, uninstalling, and troubleshooting.](https://docs.pieces.app/products/meet-pieces/linux-installation-guide/flatpak)

[Download repository file](https://builds.pieces.app/pieces-flatpak-repo/pieces-flatpak.flatpakrepo)

The graphical way — no terminal required. Download the Pieces repository file, then follow the steps below in your software center (GNOME Software, KDE Discover, or similar).

1. Open the downloaded file to add the Pieces repository to your software center.
2. Search for PiecesOS in your software center and install it.
3. Search for the Pieces Desktop App and install it, then launch PiecesOS before opening the app.

Prefer the command line? Run these commands in order.

1. Add the Flathub repository, which provides the shared runtime dependencies Pieces requires.

```
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
```

Safe to run even if Flathub is already set up — it's skipped if the repository already exists.

2. Add the official Pieces repository, which hosts both PiecesOS and the Pieces Desktop App.

```
flatpak remote-add --user --if-not-exists --from pieces-flatpak https://builds.pieces.app/pieces-flatpak-repo/pieces-flatpak.flatpakrepo
```

The --user flag installs it for your account only, so no sudo is required.

3. Install PiecesOS, the on-device engine that powers everything — Long-Term Memory, local AI, and MCP.

```
flatpak install -y pieces-flatpak com.pieces.os
```

This can take a few minutes while Flatpak downloads the required runtime dependencies.

4. Install the Pieces Desktop App, your hub for saving, searching, and managing snippets, screenshots, and developer resources.

```
flatpak install -y pieces-flatpak com.pieces.pfd
```

5. Start PiecesOS first. It runs as a background service the Desktop App connects to, and the app won't launch it automatically.

```
flatpak run com.pieces.os
```

6. Once PiecesOS is running, launch the Pieces Desktop App. After the first launch, both appear in your application menu.

```
flatpak run com.pieces.pfd
```

Always start PiecesOS before the Desktop App.

## Snap

A good fit for Ubuntu. Requires snapd and sudo access.

[Requirements, connecting interfaces, updating, and troubleshooting.](https://docs.pieces.app/products/meet-pieces/linux-installation-guide/snap)

Ubuntu 22.04+ with snapd is required. Run these commands in order — Snap installs system-wide, so they use sudo.

1. Install PiecesOS, the on-device engine that powers everything — Long-Term Memory, local AI, and MCP.

```
sudo snap install pieces-os
```

2. Connect PiecesOS to the system's process-control interface, which it needs to run correctly.

```
sudo snap connect pieces-os:process-control :process-control
```

3. Install the Pieces Desktop App.

```
sudo snap install pieces-for-developers
```

4. Connect the remaining system interfaces. This prints a command — copy and run it to finish setup.

```
pieces-os.doctor
```

Required for full functionality, including features like LTM audio.

5. Launch the Pieces Desktop App. After the first launch, it also appears in your application menu.

```
pieces-for-developers
```