Zhenzhu
Workflow & Anki

AnkiConnect on Mac: Setup, Terminal Check, and Fixing App Nap & Bundle ID Errors

To install AnkiConnect on a Mac, open Anki Desktop, go to Tools → Add-ons → Get Add-ons, enter code 2055492159, and quit and reopen Anki completely. If AnkiConnect later stops responding while Anki sits behind your browser or video player, the cause is usually macOS App Nap, Anki's net.ankiweb.launcher bundle ID change on older installs, or a missing entry in webCorsOriginList.

Install AnkiConnect on Mac (code 2055492159)

Start with Anki Desktop, which is free from apps.ankiweb.net. Open it, go to Tools → Add-ons → Get Add-ons..., and paste code 2055492159. AnkiConnect is free, listed on its AnkiWeb add-on page, and maintained in the official Anki-Connect repository.

Next, restart Anki completely. Choose Anki → Quit Anki from the macOS menu bar (or press Command + Q) rather than clicking the red close button on the window. Closing the window leaves the old process running without loading the new add-on. Reopen Anki, open your active profile, and keep Anki running whenever you mine cards.

Under the hood, AnkiConnect starts a local HTTP server on 127.0.0.1 port 8765. Browser extensions, subtitle players, and desktop dictionary tools talk to that local address so you can send a new 生词 (shēngcí, "new unfamiliar vocabulary word") or full 例句 (lìjù, "example sentence") to your deck without switching windows.

The first time a client connects, AnkiConnect displays a confirmation popup inside Anki Desktop asking whether to grant permission. Because you are usually reading in Safari, Chrome, or a video player when that happens, the popup sits hidden behind your active window and the mining tool looks frozen. Bring Anki to the front and approve it.

Test AnkiConnect in Terminal in 10 seconds

Before editing any JSON config or installing extra add-ons, run three short checks in Terminal. Each one narrows down where a connection is breaking.

1. Ask AnkiConnect for your deck list

With Anki open on your profile, run this command in Terminal:

curl -s --request POST http://127.0.0.1:8765/ --header 'Content-Type: application/json' --data '{"action":"deckNames","version":6,"params":{}}'

A healthy response returns your deck list:

{"result":["Default"],"error":null}

Current AnkiConnect (which requires Anki Desktop 26.08 or later) also serves JSON-RPC 2.0 on http://127.0.0.1:8765/api/v1 alongside the legacy endpoint above. You can check what that command returned to diagnose the layer that failed:

  • Empty output or exit code 7 (could not connect): Nothing is listening on port 8765. Anki is closed, AnkiConnect is disabled, or you did not fully quit and reopen Anki after installing it.
  • An error string about an API key: You set apiKey in AnkiConnect's config, so every client must send the matching key.
  • Valid JSON deck list returned: AnkiConnect itself is healthy. Any remaining failure is inside your browser extension's CORS origin list or the mining app's field mapping.

2. Check which process owns port 8765

Run lsof -i :8765. When Anki is running properly, you will see Anki listening on localhost:8765. If the command prints nothing, the add-on server never started. If a different application appears, another local tool has claimed port 8765, so either quit that tool or move AnkiConnect to a different webBindPort.

3. Check Anki's current macOS bundle ID

Run osascript -e 'id of app "Anki"'. Current Anki builds using the launcher report net.ankiweb.launcher, while older standalone builds reported net.ankiweb.dtop. Knowing which build you have explains why older App Nap Terminal tutorials fail.

Fix App Nap and the bundle ID change on macOS

App Nap is macOS power management that throttles applications whose windows are hidden or minimized. Because Anki sits behind your browser, PDF reader, or media player during immersion, macOS can suspend Anki mid-session. Your curl check works right after you click Anki, then starts timing out two minutes later while you read.

Why old Terminal commands stopped working

For years, the standard fix was writing NSAppSleepDisabled to Anki's macOS preference domain:

  • defaults write net.ankiweb.dtop NSAppSleepDisabled -bool true
  • defaults write net.ichi2.anki NSAppSleepDisabled -bool true
  • defaults write org.qt-project.Qt.QtWebEngineCore NSAppSleepDisabled -bool true

When Anki switched to its launcher packaging, its bundle ID changed from net.ankiweb.dtop to net.ankiweb.launcher. Because the launcher spawns the underlying Python and Qt runtime, the old net.ankiweb.dtop commands stopped matching, and as documented in the Anki Forums bundle ID thread, running defaults write net.ankiweb.launcher NSAppSleepDisabled -bool true failed to stop App Nap as well.

The clean current fix: update Anki and AnkiConnect

Current AnkiConnect requires Anki Desktop 26.08 or later (tested on 26.08 and 26.09.4) and suppresses macOS App Nap automatically as soon as its HTTP listener starts. The suppression lasts until Anki quits, while still letting your Mac sleep normally when you close the lid. You do not need any defaults write commands or a separate App Nap add-on once both are up to date.

Tip: In Anki, open Tools → Add-ons → Check for Updates and verify your Anki Desktop version in Anki → About Anki. If you are on Anki 26.08 or later with current AnkiConnect, App Nap is handled automatically.

Fallback for older Anki builds

If an older plugin keeps you on an earlier Anki build that already exposes aqt._macos_helper, install the companion add-on 139678305, macOS : Disable App Nap, and restart Anki. It calls Anki's built-in macos_helper.disable_appnap() helper on startup. To verify that App Nap is actually off, open Activity Monitor, switch to the Energy tab, and check the App Nap column for Anki.

Workarounds to avoid unless stuck

You may still see two older workarounds online:

  • Global App Nap disable: Running defaults write NSGlobalDomain NSAppSleepDisabled -bool YES blocks App Nap across every app on your Mac, which hurts laptop battery life. If you use it temporarily during a study session, revert it afterward with defaults delete NSGlobalDomain NSAppSleepDisabled.
  • Editing Info.plist: Adding LSAppNapIsDisabled inside /Applications/Anki.app/Contents/Info.plist requires re-signing the app bundle with codesign, and every Anki update overwrites the edit.

Configure webCorsOriginList and local permissions

In Anki, open Tools → Add-ons, select AnkiConnect, and click Config. The default JSON looks like this:

Config keyDefault valueWhat it controls
webBindAddress"127.0.0.1"Local loopback IP address AnkiConnect listens on
webBindPort8765Local HTTP port for API requests
apiKeynullOptional secret token if you require authentication
webCorsOriginList["http://localhost"]Browser origins permitted to call AnkiConnect
ignoreOriginList[]Origins for which permission prompts are suppressed

Browser extensions and web players need an origin

Chrome extensions, Firefox extensions, and web apps send an HTTP Origin header, and AnkiConnect blocks any origin missing from webCorsOriginList. For Yomitan in Chrome, open chrome://extensions, turn on Developer mode, and copy the 32-letter extension ID. Its origin is chrome-extension://<your-extension-id>. For the web-hosted player asbplayer, add https://app.asbplayer.dev.

A combined list that keeps the default localhost entry alongside Yomitan and asbplayer looks like this:

["http://localhost", "chrome-extension://<your-32-letter-id>", "https://app.asbplayer.dev"]

Native desktop tools do not use browser CORS

Local scripts and native macOS apps talk to http://127.0.0.1:8765 or http://localhost:8765 directly without a browser origin header. Tools such as mpvacious or a native menu-bar dictionary do not need entries in webCorsOriginList; they only need Anki running and the first-time permission dialog approved.

Watch out: AnkiConnect reads its config only at startup. After saving any change to webCorsOriginList or webBindPort, press Command + Q to quit Anki completely and reopen it.

Troubleshooting table for Chinese mining tools on Mac

When you mine a 生词 (shēngcí, "new unfamiliar vocabulary word") from web articles or video 字幕 (zìmù, "subtitles; captions") on macOS, each tool hits AnkiConnect in a slightly different way. Zhenzhu is our app, included here alongside the other common Mac setups.

ToolHow it talks to localhost:8765Common Mac failureExact fix
Yomitan (Chrome / Firefox)Browser extension sending an extension originCORS origin rejected or wrong portAdd chrome-extension://<id> to webCorsOriginList, point Yomitan to http://127.0.0.1:8765, and quit and reopen Anki
asbplayerWeb app or browser extension with an originOrigin blocked when mining from streaming videoAdd https://app.asbplayer.dev (or the extension ID) to webCorsOriginList, then restart Anki
mpv + mpvaciousLocal Lua script calling localhost directlyAnki throttled by App Nap behind mpv, or hidden permission promptUpdate Anki and AnkiConnect (or use add-on 139678305 on older builds) and approve the prompt in Anki
Zhenzhu (our app)Native macOS app calling http://localhost:8765 directlyFirst-run permission popup behind your browser or Anki closedBring Anki to the front, accept the permission prompt, and check Settings → Anki Integration

For full video-to-Anki setups on macOS, compare our guides on subs2srs alternatives for Mac and Chinese sentence mining to Anki on macOS.

Triage order when a card fails to send

  1. Confirm Anki Desktop is open, unlocked, and sitting on the profile that holds your deck.
  2. Run the curl deckNames check in Terminal to confirm port 8765 answers.
  3. Switch to Anki and check for a waiting AnkiConnect permission popup behind other windows.
  4. For browser tools, verify your exact origin inside webCorsOriginList and restart Anki.
  5. If requests work right after switching to Anki and fail a minute later, update Anki and AnkiConnect so App Nap suppression is active.

Using AnkiConnect with Zhenzhu on macOS (or skipping it)

Zhenzhu, the app we build, is a native macOS 15+ menu-bar Chinese popup 词典 (cídiǎn, "dictionary") and sentence-mining app built by indie developer Minh. It connects directly to http://localhost:8765 without requiring edits to webCorsOriginList, detects both net.ankiweb.launcher and net.ankiweb.dtop, and triggers the standard requestPermission prompt on first connect.

Once approved, you can capture text by selection, hover, or on-device OCR snip and send a 中文 (Zhōngwén, "Chinese language") word or sentence 卡片 (kǎpiàn, "card") straight to Anki with context sentences, audio, and screenshots.

When to skip AnkiConnect completely

If keeping Anki Desktop open in the background feels heavy on your Mac, you do not have to use AnkiConnect at all. Zhenzhu includes built-in local FSRS flashcards so you can mine and do your daily 复习 (fùxí, "to review") inside one menu-bar window. Keep Anki if you already manage a large collection there or want mobile sync through AnkiWeb; otherwise, built-in FSRS removes the local server setup completely.

For a broader comparison of Mac lookup tools, see best Chinese dictionary for Mac.

Zhenzhu Free and Pro

  • Free: free forever with no account or time limit. Includes unlimited dictionary lookups, sentence translation, word breakdowns with HSK context, and speech, plus 15 new mined cards per month (shared between Zhenzhu and Anki) and 20 OCR reads per month.
  • Pro: a one-time purchase of $29 for lifetime updates across 3 Macs, with no subscription (early supporter price $9, regular price $29).

How this guide was made

Research and drafting were AI-assisted. Every command, config key, bundle ID behavior, Chinese word, and product claim was verified against the official Anki-Connect documentation, Anki Forums reports, CC-CEDICT, and Zhenzhu's macOS source code.

Read Chinese on your Mac without friction

Selection lookup, on-device OCR, pinyin tone marks, HSK context, and 1-click Anki export. Try Zhenzhu Free today on macOS 15+.

Download Free for Mac

More Practical Guides

Workflow & Anki9 min read

subs2srs for Mac: Modern Alternatives for Chinese Learners (2026)

Read guide
Workflow & Anki9 min read

How to Make Anki Cards from Hardcoded Chinese Subtitles

Read guide