Install & Compatibility
Where this runs
tested against v2.1.25 · 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
installs and imports cleanly · install 0.0s · import 0.000s · 26.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.682s · 55MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Collection
✓ from anki.collection import Collection
The primary class for interacting with an Anki collection database.
Note
✓ from anki.notes import Note
Represents an Anki note, containing fields and a note type (model).
Model
✓ from anki.models import Model
Represents an Anki note type, defining fields and card templates.
This quickstart demonstrates how to open an existing Anki collection database and retrieve basic information about it. It requires the path to a `collection.anki2` file, which is typically found within your Anki profile folder. Ensure Anki desktop is not running when accessing the database directly to prevent locking issues or data corruption.
import os
from anki.collection import Collection
from anki.errors import DBError
# NOTE: This example requires an existing Anki collection database.
# If you don't have one, create a dummy profile in Anki desktop.
# Replace 'path/to/your/collection.anki2' with the actual path.
# On Linux/macOS: ~/.local/share/Anki2/User 1/collection.anki2
# On Windows: %APPDATA%\Anki2\User 1\collection.anki2
collection_path = os.environ.get('ANKI_COLLECTION_PATH', 'collection.anki2') # Placeholder/default
try:
# Connect to the collection
col = Collection(collection_path)
# Example: Print some collection statistics
print(f"Collection path: {col.path}")
print(f"Total notes: {col.note_count()}")
print(f"Total cards: {col.card_count()}")
# Example: Get the first 5 notes
note_ids = col.find_notes("nid:*")[:5]
for nid in note_ids:
note = col.get_note(nid)
print(f" Note ID: {note.id}, Model: {note.model()['name']}, Tags: {note.tags}")
# Close the collection (important to avoid database locking/corruption)
col.close()
except DBError as e:
print(f"Error opening or interacting with Anki collection: {e}")
print("Please ensure the ANKI_COLLECTION_PATH environment variable is set correctly and Anki is not running.")
except FileNotFoundError:
print(f"Collection database not found at '{collection_path}'.")
print("Please ensure the ANKI_COLLECTION_PATH environment variable points to a valid Anki collection.anki2 file.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingAnki's internal database schema (`collection.anki2`) can change between major Anki desktop application versions. Direct database manipulation or reliance on specific schema details without using the library's abstraction layer can lead to data corruption or scripts breaking with new Anki releases.fixAlways use the `anki.collection.Collection` and related classes for interacting with the database. Avoid direct SQL queries unless absolutely necessary and be prepared to update code with each major Anki release. Consult Anki's official add-on development documentation.
affects: All versions, especially across major Anki desktop updates.
gotchaThe `anki` PyPI package is the *backend* library for the Anki desktop application, not a high-level API for generating `.apkg` files or building decks from scratch in a simple manner. For creating new Anki decks programmatically, `genanki` is a more appropriate and user-friendly library.fixIf your goal is to generate `.apkg` files, consider using `genanki` (available on PyPI). If you intend to write Anki add-ons or interact deeply with an existing Anki collection, `anki` is the correct library.
affects: All versions
gotchaAccessing the Anki collection database (`collection.anki2`) directly while the Anki desktop application is running can lead to database corruption or file locking errors. The library expects exclusive access.fixEnsure the Anki desktop application is fully closed before attempting to open or modify a collection using the `anki` library. Always call `col.close()` when you are finished with the collection object.
affects: All versions
gotchaThe `anki` package is designed to run within the Anki application's environment or a carefully managed external script. It can have complex interactions with Python's environment, especially concerning paths and module loading, which might cause issues if not configured correctly.fixWhen developing external tools, thoroughly test your script's ability to locate and load the Anki collection. For add-on development, adhere to Anki's add-on development guidelines which implicitly handle the environment.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'anki'
The 'anki' module is not installed in the Python environment.
fixInstall the 'anki' module using pip: 'pip install anki'.
ImportError: cannot import name 'Collection' from 'anki'
The 'Collection' class is not directly importable from the 'anki' module.
fixImport 'Collection' from 'anki.collection': 'from anki.collection import Collection'.
ModuleNotFoundError: No module named 'aqt'
The 'aqt' module is not installed or accessible in the Python environment.
fixEnsure that Anki is installed correctly and that the 'aqt' module is available in your Python path.
ModuleNotFoundError: No module named 'speechd'
The 'speechd' module is not installed in the Python environment.
fixInstall the 'speechd' module using pip: 'pip install speechd'.
ModuleNotFoundError: No module named 'PyQt5.QtWebEngineWidgets'
The 'PyQt5.QtWebEngineWidgets' module is not installed in the Python environment.
fixInstall the 'PyQt5.QtWebEngineWidgets' module using pip: 'pip install PyQt5.QtWebEngineWidgets'.
Upgrade
Version history
26.8.1latest on PyPI · released Aug 5, 2026
Audit
Dependencies
markdownrequiredUsed for parsing Markdown within Anki note fields.