Installation Guide | macOS
The following guide will help you install and run both PiecesOS and the Pieces for Developers Desktop Application quickly and easily.
Recommended Installation Method
Click the buttons below to download Pieces for your macOS device.
System Requirements
There are (2) requirements for installing Pieces on your macOS device:
-
Compatible OS Version—macOS 12.0 (Monterey) or higher
-
Compatible installer for your device’s architecture—Apple Silicon (ARM) or Intel
Click here for a quick guide on determining your OS type, and here for how to check your device’s CPU architecture.
Component | Minimum | Recommended | Notes |
|---|---|---|---|
CPU | Any modern CPU | Multi-core CPU | Avoid dual-core processors—aim for at least a 4-core CPU. |
RAM (Local Mode) | 8 GB total system RAM with 2 GB free | 16 GB total system RAM or more | Applies when PiecesOS is running locally. |
RAM (Cloud Mode) | 8 GB total system RAM with 1 GB free | 16 GB total system RAM or more | Applies when PiecesOS is running in cloud mode. |
Disk Space | 2 GB minimum (1 GB for PiecesOS + 0.5–1 GB for data), with at least 4 GB free | 8 GB with at least 6 GB free or more | Ensure additional free space for data storage and future growth. |
Install the PKG
Once you’ve downloaded the correct .pkg file, it’s time to run the installer.
Open the Installer
Double-click the .pkg file to launch the macOS installer.
Follow the On-Screen Prompts
Navigate through the introduction screen, select the install location, and enter your administrator credentials if prompted, then click Install Software.
Alternative Installations
If you cannot use the .pkg installer for any reason, you have other options.
You can click either of the links below for documentation on installing standalone .dmg files or by using Homebrew in your Mac’s terminal:
macOS 12.0 (Monterey) or higher
macOS 12.0 (Monterey) or higher
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-osin your terminal to install the Piecesbrewpackage.
Install the DMG
After downloading the correct .dmg file, it’s time to install the Pieces Desktop App.
Open your Downloads folder (or wherever you saved the installer) and look for the .dmg file you just downloaded (e.g., Pieces.dmg).
Mount the DMG
Double-click the .dmg file to mount it.
Drag & Drop into Applications
Drag the application icon from the mounted .dmg window into your Applications folder.
Eject the DMG
Go back to Finder, right-click the mounted image, and select Eject to unmount it.
Install Using Homebrew
Alternatively, you may opt to install Pieces via Homebrew in your terminal:
Open Terminal
Launch the Terminal app on your macOS device.
Run the Brew Command
Paste brew install --cask pieces into your terminal and press Enter
This command installs both the Pieces Desktop App and PiecesOS cask. If prompted, enter your administrator password.
Wait for Installation to Complete
Homebrew will download and install the necessary files. Once it’s done, you’ll see a message indicating successful installation.
Post-Installation Tips
Read the documentation below for some tips and information to make sure you’re up and running with the latest version(s) of PiecesOS and the Pieces Desktop App, as well as steps to uninstall Pieces software from your Apple device.
Updating
The Pieces Desktop App automatically downloads and installs new updates.
You can also manually check for updates to PiecesOS and the Pieces Desktop App by clicking the Profile icon nested in the Search Bar at the top of your Pieces Desktop App view, then selecting Check for Desktop App Updates or Check for PiecesOS Updates.
Uninstalling
On your macOS device, navigate to Finder, then select Applications.
Scroll or search until you find both Pieces and PiecesOS. Right-click on these two applications and select Move to Trash.
Additional Resources
Click here for additional documentation on troubleshooting or reach out to support.