Mosaic
Menu

Installation

Install Mosaic

Get Mosaic running without installing Python yourself.

Before you start

  • A Windows 10 or 11 PC, or an Apple Silicon Mac running macOS 13 or newer
  • Space for a window at least 1,300 pixels wide at your display scaling
  • An internet connection for the first launch, when Mosaic downloads its dependencies
  • Enough time for that one-time setup to finish; the duration depends on your connection and computer

You do not need to install Python yourself. Mosaic's launcher handles the setup the first time you run it.

Step 1

Download Mosaic

Download the zipped repository from GitHub.

Download Mosaic

Your browser normally saves the zip in Downloads.

Step 2

Extract the zip

Find mosaic_python-main.zip in your Downloads folder.

Windows

Right-click the file, choose Extract All…, pick a location, and select Extract. A plain folder such as C:\Mosaic keeps saved maps and exports out of OneDrive.

Mac

Double-click the zip. Finder creates an extracted folder next to it.

You should now have a folder called mosaic_python-main.

Step 3

Run Mosaic

Windows

  1. Open the mosaic_python-main folder.
  2. Double-click run_mosaic.bat.
  3. If Windows shows “Windows protected your PC,” click More info, then Run anyway.
  4. Let the black window finish downloading the dependencies.
  5. Leave that window open while you use Mosaic.

Mac

  1. Open the mosaic_python-main folder in Finder.
  2. Right-click or Ctrl-click run_mosaic.command and choose Open.
  3. Click Open in the warning. Later launches can use a normal double-click.
  4. Let the Terminal window finish downloading the dependencies.
  5. Leave that window open while you use Mosaic.

From Terminal, you can instead run chmod +x run_mosaic.sh && ./run_mosaic.sh from the extracted folder.

Troubleshooting

Windows says “Windows protected your PC”

Click More info, then Run anyway.

Mac says the file is from an unidentified developer

Right-click or Ctrl-click run_mosaic.command, choose Open, then click Open in the warning. Later launches can use a normal double-click.

Windows asks for the Microsoft Visual C++ Runtime

Save and run VC_redist.x64.exe from the page Mosaic opens, accept the permission prompt, then double-click run_mosaic.bat again.

Mac asks for the Command Line Tools

Click Install in the system dialog and wait for it to finish, then double-click run_mosaic.command again.

First launch is stuck at “Installing dependencies”

The first run downloads Mosaic's scientific Python packages and can take several minutes. Watch the black window on Windows or Terminal on Mac for progress. If it stops producing output for an extended period, close the window and try again.