Install & Compatibility
Where this runs
tested against v26.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.3s · import 0.624s · 609MB
601MB installed
● package 601MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Collection
✓ from anki.collection import Collection
anki-release itself is not imported for functionality; it enables importing from the 'anki' package for backend operations.
mw
✓ from aqt import mw
For accessing the main Anki window and its functionalities when extending the GUI (e.g., add-ons).
This quickstart demonstrates installing `anki-release` and then provides a minimal example of how to interact with the Anki backend (`anki` package) by opening an Anki collection. This package primarily sets up the environment, and direct programmatic interaction is typically done through the `anki` and `aqt` libraries it depends on.
import os
from anki.collection import Collection
from anki.stdrepl import repl
# NOTE: For anki-release, the primary use case is to ensure backend dependencies.
# The actual Anki backend interaction is via the 'anki' package.
# Create a temporary Anki collection for demonstration
# In a real scenario, you'd likely open an existing collection.
COLLECTION_PATH = os.environ.get('ANKI_TEST_COLLECTION_PATH', 'temp_collection.anki2')
# Ensure the directory exists if not in the current working directory
collection_dir = os.path.dirname(COLLECTION_PATH)
if collection_dir and not os.path.exists(collection_dir):
os.makedirs(collection_dir)
# Open or create an Anki collection
col = Collection(COLLECTION_PATH)
print(f"Opened Anki collection at: {col.path}")
# Example: Get number of notes (0 for a new collection)
print(f"Number of notes: {col.note_count()}")
# Clean up the temporary collection if created new
# In a real application, you'd manage persistence carefully.
# col.close()
# if not os.environ.get('ANKI_TEST_COLLECTION_PATH'):
# os.remove(COLLECTION_PATH)
# Anki's internal Python environment might use a custom REPL for debugging
# For general scripting, standard Python interactions apply.
# You might interact with objects like col.models, col.decks, etc.
Debug
Known issues
breakingAnki (and thus anki-release) is licensed under AGPL-3.0-or-later. Using Anki's backend in a closed-source application generally requires a specific exception from the developers or adherence to the AGPL's terms, which often means open-sourcing your derived work.fixConsult the Anki license (AGPL-3.0-or-later) and consider its implications for your project's licensing. If creating a closed-source application, contact Anki's developers for an exception or consider alternatives.
affects: All versions
gotchaThe `anki-release` package provides the *backend* and GUI components for the desktop application, not the Anki desktop application installer itself. Running `pip install anki-release` will set up the Python environment but won't install the executable application. Users typically interact with the Anki desktop app downloaded from AnkiWeb.fixFor the full desktop application, download it from https://apps.ankiweb.net. Use `anki-release` for programmatic access or add-on development within a Python environment.
affects: All versions
breakingAnki's internal architecture, especially how it handles the collection backend, has undergone significant changes (e.g., transition to Rust-based `rslib` wrapped by Python). These changes can affect direct interactions with the `anki` package, potentially breaking code relying on older internal structures.fixAlways refer to the latest Anki developer documentation for backend interactions. Stay updated with Anki's release notes for changes impacting the `anki` Python package API. Test thoroughly after major Anki desktop updates.
affects: Versions 2.1.50+ (or 25.x.x+ in new numbering)
gotchaThe version numbers for `anki-release` (e.g., 25.9.2) are directly tied to the Anki desktop application's release versions, not independent Python package versions. This means changes are frequent and often non-backward compatible without clear 'major' version breaks in the traditional Python sense.fixPin `anki-release` to a specific version in your `requirements.txt` to ensure stability. Regularly check Anki's official release notes on GitHub (ankitects/anki) for potential breaking changes relevant to the backend.
affects: All versions
gotchaWhen importing or updating packaged decks (.apkg files) using the Anki backend, be aware that scheduling information might be included unintentionally. This can lead to unexpected review intervals or card states if not handled correctly.fixWhen importing shared decks programmatically, ensure you understand the options for stripping scheduling information if it's not desired. Anki 23.10+ (and thus 25.x.x) allows removing learning progress during import.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aqt'
This error occurs when the 'aqt' module is not found, often due to an incomplete or incorrect Anki installation.
fixEnsure that Anki is properly installed and that your Python environment is correctly set up. Reinstalling Anki may resolve the issue.
ImportError: No module named QtWebKit
This error indicates that the QtWebKit module is missing, which is required by Anki for its graphical interface.
fixInstall the missing QtWebKit module using your package manager. For example, on Debian-based systems, you can run 'sudo apt-get install python-qt4'.
ImportError: cannot import name 'ImportLogWithChanges' from 'anki.collection'
This error occurs when there is a version mismatch between Anki and its dependencies, leading to missing or changed attributes.
fixEnsure that all Anki dependencies are up to date and compatible with your Anki version. Reinstalling Anki and its dependencies may resolve the issue.
ImportError: cannot import name 'builder' from 'google.protobuf.internal'
This error occurs when the 'builder' module is missing from the 'google.protobuf.internal' package, often due to an outdated or incompatible version of the protobuf library.
fixUpdate the protobuf library to the latest version compatible with Anki. You can do this by running 'pip install --upgrade protobuf'.
ImportError: No module named '_sqlite3'
This error indicates that the '_sqlite3' module is missing, which is required by Anki for database operations.
fixInstall the SQLite development libraries and rebuild Python to include SQLite support. On Debian-based systems, you can run 'sudo apt-get install libsqlite3-dev' and then rebuild Python.
Upgrade
Version history
26.5latest on PyPI · released Jun 16, 2026
Audit
Dependencies
ankirequiredCore Anki backend functionality.
aqtrequiredAnki's Qt-based GUI components (desktop frontend).
pyqt6requiredGUI framework dependency for aqt.
attrsrequiredDependency for structured attributes.
requestsrequiredHTTP library for network operations.