---

Issues | Linux

Learn about what troubleshooting steps to take if PiecesOS or the Pieces Desktop App isn’t working as expected on your Linux device.

---

Versions & Updates

Many issues can stem from running outdated versions of PiecesOS or the Pieces Desktop App on Linux.

Updating PiecesOS

On Linux, PiecesOS and the Pieces Desktop App are distributed via snaps (for Ubuntu-based systems).

To update PiecesOS on Linux:

1. Run snap info pieces-os to check the current version of PiecesOS

2. Run sudo snap refresh to update PiecesOS if a newer version is available

Updating the Pieces Desktop App

Similar to PiecesOS, you can update the Pieces Desktop App by:

1. Running snap info pieces-for-developers to check the current version

2. Running sudo snap refresh to apply any available updates

Common Installation Issues

Official support is provided for Ubuntu 22+ and Ubuntu-based distributions. Other distributions may work but aren’t guaranteed.

Checking Distribution Compatibility

Ensure you’re running a supported Ubuntu-based distribution.

If not, consider switching to a supported environment, as installation on non-Ubuntu distributions isn’t guaranteed.

Updating Snapd

Snap-based installations require an up-to-date snap daemon:

• Run sudo snap refresh to ensure snapd and its packages are current

Adjusting Graphics & Display Settings

If installation or UI issues persist:

• Consider switching between x11 and Wayland

• Adjust GPU drivers or graphics configurations as needed

Checking System Information

You can verify your system’s hardware configuration and ensure it meets recommended specifications by running specific commands in your terminal.

• Run lscpu for CPU information

• Run lspci | grep -i vga for GPU information

Confirm that your CPU, GPU, and memory resources are sufficient for running PiecesOS and local AI models (if applicable).

Click here for documentation on what we recommend for minimum device specifications if you plan on utilizing a local LLM.

Consulting Online Resources

If you encounter persistent installation issues, consult online forums or community guides related to snap and Ubuntu-specific troubleshooting steps.

Restart & Retry

If you’ve updated components, checked hardware, and adjusted configurations without success, restart your machine and try again.

If the problem persists, please open a GitHub issue for further assistance, or book a call with our engineers.