Install & Update Help

Choose the right installer, confirm compatibility, and fix common setup or update issues.

Understand what Pieces installs and how the apps work together.

Check macOS version, CPU type, permissions, and installer options.

Check system updates, App Installer, dependencies, and hardware.

Confirm distribution compatibility and resolve Snap or display issues.

Quick fixes

Cannot open app package: restricted capabilities (Windows)

This usually happens on a Windows PC where you are not an administrator.

Try the standalone .exe installer instead of .appinstaller. It sometimes bypasses App Installer restrictions.
If that also fails, search for Pieces Desktop in the Microsoft Store. The Store version tends to work better on managed machines.
Ask your IT admin to allowlist the Pieces installer if neither option works.

Wrong architecture or permission denied (macOS)

macOS may block the installer if the CPU architecture does not match or Gatekeeper prevents unsigned apps.

Check your chip: click Apple menu → About This Mac and look for Apple Silicon (M-series) or Intel.
Download the correct installer: Apple Silicon for M1/M2/M3/M4, Intel for older Macs, or Universal if unsure.
If macOS says the app cannot be opened, go to System Settings → Privacy & Security and click Open Anyway.

Snap or package update issues (Linux)

Snap packages may need a manual refresh, or Flatpak repos may not be configured correctly.

Run sudo snap refresh to update Snap packages.
If using Flatpak, confirm the Pieces repo is added (see the Linux guide for the repo URL).
Check that your display server (X11 or Wayland) is supported. Some distros require extra display permissions.

Use the platform guide that matches your computer.

Include your operating system, version, CPU architecture, and installer type.