Install Mosaic

About five minutes from download to a running map. No Python knowledge required.

Before you start

• A Windows 10 / 11 PC, or a Mac running macOS 12 or newer
• An internet connection (first launch downloads about 200 MB)
• About 5 minutes of patience for the first launch

You do not need to install Python yourself. Mosaic ships with a launcher that sets everything up the first time you run it.

1. Download Mosaic

Download the zipped repository from GitHub.

Download mosaic_python.zip

About 4 MB. Saved to your usual Downloads folder.

2. Extract the zip

Find the downloaded mosaic_python-main.zip in your Downloads folder.

Windows: right-click the file → Extract All… → pick a place you'll remember (Desktop or Documents is fine) → Extract.
Mac: double-click the file. Finder will create a folder next to the zip with the same name.

You should now have a folder called mosaic_python-main.

3. Run Mosaic

On Windows

Open the mosaic_python-main folder.
Double-click run_mosaic.bat.
If Windows shows a blue "Windows protected your PC" warning, click More info, then Run anyway. This warning appears because the launcher script downloads its own setup tool (uv) on the first run; no installer is "signed" yet.
A black window opens and starts downloading dependencies. This takes 2–3 minutes the first time. Subsequent launches are instant.
When the Mosaic window appears, you're set. Leave the black window open while you use Mosaic; closing it closes the app.

On Mac

Open the mosaic_python-main folder in Finder.
Right-click (or Ctrl-click) run_mosaic.command and choose Open. macOS will warn that the file is from an unidentified developer; click Open in the dialog. You only need to do this the first time — later launches can use a normal double-click.
A Terminal window opens and starts downloading dependencies. This takes 2–3 minutes the first time. Subsequent launches are instant.
When the Mosaic window appears, you're set. Leave the Terminal window open while you use Mosaic; closing it closes the app.

Prefer the command line? cd into the extracted folder and run chmod +x run_mosaic.sh && ./run_mosaic.sh instead.

4. Try the bundled sample

Inside the folder you extracted, the shapefiles/ subfolder contains a ready-to-use North Carolina precinct map. In Mosaic, choose Load shapefile and pick shapefiles/North_Carolina_Simplified.shp. Hit Run and watch the map redraw each iteration.

When you're ready to use your own data, the shapefile guide covers where to find shapefiles and what Mosaic needs them to look like.

If something doesn't work

Windows says "Windows protected your PC"

Click More info, then Run anyway. Mosaic is an unsigned app distributed as source code; SmartScreen flags every unsigned launcher on first run, regardless of what it does.

Mac says "cannot be opened because it is from an unidentified developer"

macOS Gatekeeper flags every unsigned launcher on first run. Right-click (or Ctrl-click) run_mosaic.command, choose Open, and click Open in the warning dialog. Subsequent launches can use a normal double-click.

"python: command not found" or similar

The launcher handles Python itself via uv. If you see this error, the launcher's network call probably failed. Check your internet connection, delete the .venv folder if one was created inside mosaic_python-main, and run the launcher again.

First launch is stuck at "Installing dependencies"

The first run downloads about 200 MB of scientific Python packages. On a slow connection this can take 5–10 minutes. Watch the black window (Windows) or Terminal (Mac) for progress; if it has been completely silent for more than 15 minutes, something is wrong. Close the window and try again.

It crashed after I loaded my own shapefile

Mosaic writes a crash log to a crashes/ folder next to the launcher. That file plus a description of what you did is what to include when filing a bug report on GitHub.

Still stuck? Open an issue on GitHub and include the crash log if you have one.