> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/setup/opening-gum-on-macos.md).

# Opening Gum on macOS

Gum is not notarized by Apple, so macOS blocks it the first time you open it. You approve it once, and after that Gum opens normally. A new release is a new download, so you approve each new copy once too.

## Download and Extract

1. Download the file for your Mac from the [latest release](https://github.com/vchelaru/Gum/releases/latest):

   * `Gum-osx-arm64.tar.xz` for Apple Silicon (M1 and later).
   * `Gum-osx-x64.tar.xz` for Intel.

   To check which one you have, open the Apple menu and select **About This Mac**. A **Chip** line starting with **Apple** means Apple Silicon. A **Processor** line mentioning **Intel** means Intel.
2. Double-click the `.tar.xz` file in Finder. macOS extracts `Gum.app` into the same folder.
3. Drag `Gum.app` into your **Applications** folder.

## Allow Gum to Open

Use either the System Settings steps or the Terminal command. Both do the same job.

### Option 1: System Settings

1. Double-click `Gum.app`. macOS shows a message saying it could not verify Gum. Click **Done**, not **Move to Trash**.
2. Open the Apple menu and select **System Settings**, then **Privacy & Security**.
3. Scroll down to the **Security** section. It shows a message that Gum was blocked. Click **Open Anyway**.
4. Enter your password or use Touch ID, then click **Open Anyway** in the dialog that appears.

The **Open Anyway** button only appears for about an hour after macOS blocks Gum. If you don't see it, double-click `Gum.app` again and then go back to **Privacy & Security**.

On macOS 14 (Sonoma) and earlier there is a shortcut: Control-click `Gum.app` in Finder, select **Open**, then click **Open** in the dialog. macOS 15 (Sequoia) removed this shortcut, so use the steps above there.

### Option 2: Terminal

Open **Terminal** (in **Applications** > **Utilities**) and run:

```sh
xattr -dr com.apple.quarantine /Applications/Gum.app
```

macOS marks every downloaded file as coming from the internet, and that mark is what makes it check the app. This command removes the mark from `Gum.app` and everything inside it. If you put `Gum.app` somewhere other than **Applications**, change the path to match.

## Folder Access Prompts

macOS asks before any app reads files in your **Desktop**, **Documents**, or **Downloads** folders, or on an external drive. The first time Gum opens a project in one of those places, you may see a message like "Gum would like to access files in your Documents folder." Click **Allow**.

If you clicked **Don't Allow**, Gum cannot read the project. To fix it:

1. Open **System Settings** > **Privacy & Security** > **Files and Folders**.
2. Find **Gum** in the list and turn on the folder your project is in.
3. Quit and reopen Gum.

## Troubleshooting

* **macOS says Gum "is damaged and can't be opened."** Run the Terminal command in [Option 2](#option-2-terminal), then open Gum again.
* **Gum is blocked again after updating.** Each new download carries a new internet mark. Approve the new copy with either option above.
* **Gum opens but can't find your project.** Check the folder access steps in [Folder Access Prompts](#folder-access-prompts).

For other setup details, see [Setup](https://docs.flatredball.com/gum/gum-tool/setup.md). To open a project from the command line, see [Launching Gum with a Project](https://docs.flatredball.com/gum/gum-tool/setup/launching-gum-with-a-project.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/gum-tool/setup/opening-gum-on-macos.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
