{"id":4421,"library":"anki","title":"Anki Core Library","description":"The `anki` package is the Python backend library for the Anki desktop flashcard application. It provides the core data models, collection management, and scheduling logic. It is primarily used for developing Anki add-ons or for advanced programmatic interaction with Anki's internal database. This is not a high-level library for generating Anki decks from scratch (for that, consider `genanki`). It tracks the Anki desktop application's versioning and has a release cadence tied to the desktop app updates.","status":"active","version":"25.9.2","language":"en","source_language":"en","source_url":"https://github.com/ankitects/anki","tags":["anki","flashcards","backend","add-on","database"],"install":[{"cmd":"pip install anki","lang":"bash","label":"Install Anki backend library"}],"dependencies":[{"reason":"Used for parsing Markdown within Anki note fields.","package":"markdown","optional":false}],"imports":[{"note":"The primary class for interacting with an Anki collection database.","symbol":"Collection","correct":"from anki.collection import Collection"},{"note":"Represents an Anki note, containing fields and a note type (model).","symbol":"Note","correct":"from anki.notes import Note"},{"note":"Represents an Anki note type, defining fields and card templates.","symbol":"Model","correct":"from anki.models import Model"}],"quickstart":{"code":"import os\nfrom anki.collection import Collection\nfrom anki.errors import DBError\n\n# NOTE: This example requires an existing Anki collection database.\n# If you don't have one, create a dummy profile in Anki desktop.\n# Replace 'path/to/your/collection.anki2' with the actual path.\n# On Linux/macOS: ~/.local/share/Anki2/User 1/collection.anki2\n# On Windows: %APPDATA%\\Anki2\\User 1\\collection.anki2\ncollection_path = os.environ.get('ANKI_COLLECTION_PATH', 'collection.anki2') # Placeholder/default\n\ntry:\n    # Connect to the collection\n    col = Collection(collection_path)\n\n    # Example: Print some collection statistics\n    print(f\"Collection path: {col.path}\")\n    print(f\"Total notes: {col.note_count()}\")\n    print(f\"Total cards: {col.card_count()}\")\n\n    # Example: Get the first 5 notes\n    note_ids = col.find_notes(\"nid:*\")[:5]\n    for nid in note_ids:\n        note = col.get_note(nid)\n        print(f\"  Note ID: {note.id}, Model: {note.model()['name']}, Tags: {note.tags}\")\n\n    # Close the collection (important to avoid database locking/corruption)\n    col.close()\n\nexcept DBError as e:\n    print(f\"Error opening or interacting with Anki collection: {e}\")\n    print(\"Please ensure the ANKI_COLLECTION_PATH environment variable is set correctly and Anki is not running.\")\nexcept FileNotFoundError:\n    print(f\"Collection database not found at '{collection_path}'.\")\n    print(\"Please ensure the ANKI_COLLECTION_PATH environment variable points to a valid Anki collection.anki2 file.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"Anki'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.","severity":"breaking","affected_versions":"All versions, especially across major Anki desktop updates."},{"fix":"If 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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Accessing 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When 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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}