Installing Kingfisher on macOS

What you need

• A Mac with Apple Silicon (M1 or later), runningmacOS 13 (Ventura) or later.
• About 1 GB of free disk space for the application and a fresh study workspace.
• Nothing else. No Node, no terminal, no database, no account.

1. Download

The current macOS build is Kingfisher 1.1.2 (build 516), published 2026-09-13 from commit fc95f4d. The file is Kingfisher-1.1.2-arm64.dmg, 159 MB, Apple Silicon only. The download button on the landing page points at the same file; so does this one.

Download Kingfisher-1.1.2-arm64.dmg

It is attached to https://github.com/mardakurt/kingfisher/releases/tag/v1.1.2.

2. (Optional) verify the download

The SHA-256 of the file above is:

a2d937740907f4ec43a714e7900b6791e7aa37f483705af193674cae335164ae

To check yours:

shasum -a 256 ~/Downloads/Kingfisher-1.1.2-arm64.dmg

The output should match. If it does not, the download was corrupted or tampered with — delete it and re-download. Nobody has to do this; it is here for the people who want to.

3. Open the DMG

Double-click Kingfisher-1.1.2-arm64.dmg in your Downloads folder. A window opens with the Kingfisher icon and a shortcut to Applications.

4. Move to Applications

Drag the Kingfisher icon onto the Applications shortcut. Eject the disk image (right-click the desktop icon, Eject, or use the eject button next to it in Finder).

5. First launch

Open Kingfisher from Applications or Spotlight. Because the file was downloaded, macOS shows its standard confirmation once — “Kingfisher” is an app downloaded from the Internet. Are you sure you want to open it? — and names Apple's check. Click Open. That is the whole first launch.

What you should not see: “cannot be opened because the developer cannot be verified”, “cannot be checked for malicious software”, or “damaged”. Those messages mean the file you have is not the build Apple notarised — check the SHA-256 above and download it again from the release page. There is no right-click workaround to apply, and no system-wide setting to change; if a genuineKingfisher 1.1.2 (build 516) download does show one of those messages, that is a bug — please report it.

Do not turn Gatekeeper off. spctl --master-disable and its relatives disable a system-wide protection for every application on the machine. Kingfisher will never ask you to do it.

6. First five minutes

Kingfisher opens on the analysis board with a game position and the tools beside it.

1. Play a few moves on the board, or click one in the Explorer.
2. Press Analyse this position.Stockfish 18 runs in the application; nothing is downloaded and nothing is sent anywhere.
3. Open the Explorer tool.It answers from Kingfisher Starter — 172,376 over-the-board games — and keeps answering twenty full moves in.
4. Open the Theory Book tool.It names the opening you are in, with its ECO code, and shows no numbers at all: a name is the only claim it makes.
5. Search a player. Players → type “Carlsen”.
6. Save something. Save to study, then quit and reopen. It is still there.

7. Updating

Kingfisher → Check for Updates… asks the release host once, when you click it, and installs a newer release with your confirmation. To update by hand instead:

1. Quit Kingfisher.
2. Download the new DMG from the landing page.
3. Drag the new Kingfisher.app over the old one in Applications. macOS asks whether to replace — confirm.
4. Your studies, repertoire, notes and preferences are kept; they live in~/Library/Application Support/kingfisher-desktop/ and are not touched by replacing the application bundle.

8. Uninstalling

1. Export a backup first if you want to keep your studies:Settings → Database → Export backup.
2. Quit Kingfisher.
3. Drag Kingfisher from Applications to the Trash.
4. Optionally, delete the application-support folder to remove the last copy of your local work: ~/Library/Application Support/kingfisher-desktop.

Troubleshooting

“Kingfisher is damaged”

That is Gatekeeper saying the same thing ascannot be checked for malicious software. Go back to step 5; right-click → Open is the supported fix.

“Another program is using its port”

That is deliberate. The desktop companion keeps your work at one fixed loopback port recorded in your profile, and Kingfisher would rather stop and tell you than open an empty workspace somewhere else. Close whatever is using the port it names, and open Kingfisher again.

Kingfisher did not get as far as a window

There is nothing on screen to copy from. The shell keeps its own log — launch, companion failures, quit — at~/Library/Application Support/kingfisher-desktop/logs/kingfisher.log.

The log is bounded to about a megabyte, it never leaves your machine on its own, and the companions pairing token is replaced with [redacted] before anything is written.

Settings → Diagnostics → Copy support information puts a few lines on the clipboard: version, build number, commit and channel, the machine, which sources are ready, which engines started, whether the companion is up. Paste that into your report — the build number is what lets a report about “1.0.0” be matched to the bytes you actually have.

Copy full diagnostic report is what to attach. Neither contains your games, studies, notes, tokens or keys.

A useful report is four sentences

What you were doing. What happened. What you expected. The support-information line.

Optional, when you want it

None of this is needed to use Kingfisher, and none of it is part of first run.

• Native engines. Settings → Engine. Each is downloaded from the project's own release page, checked against a recorded SHA-256, and made to complete a real search before it is listed as ready. They run with your user account's permissions and are not sandboxed; the interface says so.
• Local tablebases. Settings → Companion → Browse… and point it at a folder of Syzygy files. The probe helper is inside the bundle; there is nothing to compile.
• A Lichess or Chess.com account, to study your own games.
• Larger reference data. Databases → Reference sources → Installlists Elite OTB, Recent Theory and High-Rated Online. The install button does the full download + checksum + install for you. Sizes are honest; pick the pack that matches the question you actually have.