---
title: "Install on macOS"
description: "Install the Tatolab app with Homebrew or from a download. The app starts the runtime, keeps it running, and lives in your menu bar."
type: "docs-page"
url: "https://tatolab.com/docs/install/macos"
site: "Tatolab"
section: "Install"
---

# Install on macOS

> Install the Tatolab app with Homebrew or from a download. The app starts the runtime, keeps it running, and lives in your menu bar.

On a Mac, Tatolab is an app. Opening it starts the runtime if it isn't running, the way Docker Desktop does, and registers it as a login item so it comes back after a restart.

## Requirements

- A Mac with Apple silicon (M1 or later). Intel Macs aren't supported.
- macOS 15 Sequoia or later.
- An administrator password, once, for the first launch.

You don't need a Vulkan SDK or any GPU drivers: the app carries everything the runtime needs.

## Install with Homebrew

```sh
brew install --cask tatolab/tap/tatolab
open -a Tatolab
```

The first command puts Tatolab in Applications, and the second opens it for [the first launch](#the-first-launch).

## Or download the app

1. Download the `.dmg` from the [latest release](https://github.com/tatolab/streamlib/releases/latest).
2. Open it and drag **Tatolab** into **Applications**.
3. Open Tatolab from Applications.

## The first launch

1. The app is signed and notarized by Apple. macOS asks you to confirm opening an app downloaded from the internet the first time; click **Open**.
2. Enter your administrator password when asked. This happens once, and does two things:
   - links `tatolab` into `/usr/local/bin`, so you can use it in Terminal;
   - creates `/Library/Application Support/Tatolab/`, which the runtime uses to make sure only one runtime runs on the Mac.

   If you cancel, the menu shows **Setup unfinished**, and **Set Up Tatolab…** in the same menu asks again.
3. The app starts the runtime and adds it to your login items. If macOS wants you to approve the login item, the app opens **System Settings → General → Login Items & Extensions**; switch Tatolab on there.

Tatolab now lives in your menu bar. Its menu has a status line, such as **Runtime running · 2 streams**, the **Run Tatolab** switch, and **Quit Tatolab**.

## Check that it works

Open a new Terminal window and run:

```sh
tatolab streams
```

```txt title="Output"
No streams in this runtime.
```

You're ready for the [quickstart](https://tatolab.com/docs/quickstart). If you don't have uv yet, [set up Python](https://tatolab.com/docs/install/python) first.

## Camera and microphone access

The first time a stream uses the camera or the microphone, macOS asks whether Tatolab may use it. The prompt names Tatolab, and macOS remembers your answer across updates. The stream starts either way: frames or audio begin as soon as you click Allow.

If you clicked Don't Allow, turn access back on in **System Settings → Privacy & Security → Camera** (or **Microphone**), and switch on Tatolab.

## Starting and stopping the runtime

- The runtime starts when you log in, and starts again by itself if it crashes. Streams you keep with `tatolab run -d` come back with it.
- **Quit Tatolab** closes the menu bar app. The runtime keeps running, and so do your streams.
- To stop the runtime, switch off **Run Tatolab** in the app's menu. It stays off until you switch it back on, even if you reopen the app or restart the Mac.

## Update

- **Homebrew:** `brew upgrade --cask tatolab`
- **Download:** download the new `.dmg` and drag Tatolab into Applications, replacing the old copy.

After updating, open Tatolab. A Homebrew upgrade stops the runtime until the app opens again, and a copy dragged over the old one leaves the old runtime running until you switch **Run Tatolab** off and on. The new version then loads the streams you kept. If one can't load under the new version, `tatolab streams` lists it as failed and says why; running `tatolab run -d` in its project loads it fresh.

## Uninstall

**Homebrew:** `brew uninstall --cask tatolab` stops the runtime, quits the app, and removes both the app and the `tatolab` command. Add `--zap` to also delete the app's settings and the record of the streams the runtime kept.

**Download:**

1. Switch off **Run Tatolab**, which stops the runtime, then choose **Quit Tatolab**.
2. Drag Tatolab from Applications to the Trash.
3. Remove the command-line link: `sudo rm /usr/local/bin/tatolab`.
4. To forget the streams the runtime kept, delete `~/Library/Application Support/Tatolab/`.

Either way, the lock folder stays until you remove it: `sudo rm -r "/Library/Application Support/Tatolab"`. Your stream projects aren't touched.

## Troubleshooting

- **`tatolab: command not found`.** Open a new Terminal window after the first launch. If it still isn't found, check that `/usr/local/bin` is on your `PATH` (`echo $PATH`), and that the first launch's administrator prompt completed.
- **`no runtime is running on this machine`.** Open Tatolab and check that **Run Tatolab** is on.
- **The menu says Needs approval in Login Items.** macOS is waiting for you to allow the runtime. Switch Tatolab on in **System Settings → General → Login Items & Extensions**; the app opens that page for you once each time it starts.
- **The menu says Setup unfinished.** The administrator prompt was cancelled or failed. Choose **Set Up Tatolab…** in the menu to try again.
- **The window opens but stays black.** Check camera access in **System Settings → Privacy & Security → Camera**. A stream with no camera to use can still run with `TestPatternSource`; try `tatolab new test-bars --test-pattern`.

More fixes are in [Troubleshooting](https://tatolab.com/docs/reference/troubleshooting).