Issues | macOS

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

Alternative Installation Methods

If you’re experiencing difficulties with installing the Pieces Desktop App, you can install the software manually by downloading the standalone .dmg installation files or by using terminal commands.

If you’re not sure which .dmg you need based on your device’s CPU, click here.

Pieces Desktop App — ARM .DMG

macOS 12.0 (Monterey) or higher

Pieces Desktop App — Intel .DMG

macOS 12.0 (Monterey) or higher

Installing via Homebrew

You can also install PiecesOS manually using Homebrew from your device’s terminal.

To do so:

Ensure Homebrew is installed on your system.
Run brew install --cask pieces-os in your terminal to install the Pieces Homebrew package.

Versions & Updates

Many issues can stem from out-of-date plugins, extensions, PiecesOS, or the desktop app itself.

Updating the Pieces Desktop App

Update the Pieces Desktop App on macOS by clicking the User Icon next to the search bar at the top of the Pieces Desktop Window. Then, click Check for Desktop App Updates or Check for PiecesOS Updates.

To check the Pieces Desktop App for updates on macOS:

Open the Pieces Desktop App

Use the Search option or locate the Pieces Desktop App within your Applications folder

Locate the Update Option

Click the User Icon to the right of the Search Bar at the top of the main app view

Check for Updates

Click the Check for Desktop App Updates option

You can also click Check for PiecesOS Updates as an alternative to doing so in from the PiecesOS system window in your taskbar.

Common Installation Issues

Common installation issues on Apple devices include having an outdated OS version or choosing the wrong installation package.

Checking OS Version

Pieces applications need at least macOS 12.0 (Monterey). If you're having installation problems, first check that your OS version is up-to-date.

To determine your Apple device’s version of macOS:

Locate the Apple Icon

Click the Apple Icon in the top-left corner of your screen

Learn More About your Mac

Select About This Mac

Find your OS Version

Under your device name (i.e. MacBook Air), look for the last line on the list, titled macOS

Checking CPU Type

Intel and Apple Silicon (ARM) devices run on entirely separate CPU architectures, so downloading the wrong package for your Apple device can cause Pieces Desktop to be rendered useless.

To determine what CPU architecture your Apple device utilizes:

Open the Apple Options

Click the Apple Icon in the top-left corner of your screen.

Locate Mac Information

Select About This Mac, and look for the Overview section. The first line will contain your CPU type:

Apple Silicon / ARM: You will see an M-Series processor (i.e., Apple M3)
Intel: You will see an Intel processor (i.e., 2.6 GHz Intel Core i7)

Once you’ve determined your CPU architecture, download the correct installation package accordingly.

Restart & Retry

If the installation fails because your macOS version is outdated or you installed the wrong package for your device's architecture, restart your machine and try the installation again from the beginning.

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