Anki Release (Dependency Locker)

25.9.2 verified Sun Apr 12 auth: no python

Anki-release is a Python meta-package designed to lock the dependencies required for the Anki desktop application's Python components, ensuring a consistent and compatible environment for developers building on the Anki backend. It does not provide direct user-facing API but facilitates the installation of the core `anki` and `aqt` libraries along with their many transitive dependencies. It follows Anki's rapid release cadence, with the current version being 25.9.2.

pip install anki-release

Common errors

error ModuleNotFoundError: No module named 'aqt' ↓

cause This error occurs when the 'aqt' module is not found, often due to an incomplete or incorrect Anki installation.

fix

Ensure that Anki is properly installed and that your Python environment is correctly set up. Reinstalling Anki may resolve the issue.

error ImportError: No module named QtWebKit ↓

cause This error indicates that the QtWebKit module is missing, which is required by Anki for its graphical interface.

fix

Install the missing QtWebKit module using your package manager. For example, on Debian-based systems, you can run 'sudo apt-get install python-qt4'.

error ImportError: cannot import name 'ImportLogWithChanges' from 'anki.collection' ↓

cause This error occurs when there is a version mismatch between Anki and its dependencies, leading to missing or changed attributes.

fix

Ensure that all Anki dependencies are up to date and compatible with your Anki version. Reinstalling Anki and its dependencies may resolve the issue.

error ImportError: cannot import name 'builder' from 'google.protobuf.internal' ↓

cause 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.

fix

Update the protobuf library to the latest version compatible with Anki. You can do this by running 'pip install --upgrade protobuf'.

error ImportError: No module named '_sqlite3' ↓

cause This error indicates that the '_sqlite3' module is missing, which is required by Anki for database operations.

fix

Install 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.

Warnings

breaking Anki (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. ↓

fix Consult 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.

gotcha The `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. ↓

fix For 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.

breaking Anki'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. ↓

fix Always 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.

gotcha The 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. ↓

fix Pin `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.

gotcha When 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. ↓

fix When 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.

Imports

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).

Quickstart

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.