AnkiHub doesnât support Python 3.14 yet due to using an outdated version of mashumaro. Please update this, thanks.
Anki 25.09.2 (3890e12c) (ao)
Python 3.14.3 Qt 6.10.2 PyQt 6.10.2
Platform: Arch Linux
When loading AnkiHub:
Traceback (most recent call last):
File "/usr/lib/python3.14/site-packages/aqt/addons.py", line 250, in loadAddons
__import__(addon.dir_name)
~~~~~~~~~~^^^^^^^^^^^^^^^^
File "/home/user/.local/share/Anki2/addons21/1322529746/__init__.py", line 28, in <module>
from . import entry_point
File "/home/user/.local/share/Anki2/addons21/1322529746/entry_point.py", line 14, in <module>
from .db import ankihub_db
File "/home/user/.local/share/Anki2/addons21/1322529746/db/__init__.py", line 1, in <module>
from .db import ( # noqa: F401
...<4 lines>...
)
File "/home/user/.local/share/Anki2/addons21/1322529746/db/db.py", line 39, in <module>
from ..ankihub_client import Field, NoteInfo, suggestion_type_from_str
File "/home/user/.local/share/Anki2/addons21/1322529746/ankihub_client/__init__.py", line 6, in <module>
from .ankihub_client import ( # noqa: F401
...<10 lines>...
)
File "/home/user/.local/share/Anki2/addons21/1322529746/ankihub_client/ankihub_client.py", line 45, in <module>
from .models import (
...<19 lines>...
)
File "/home/user/.local/share/Anki2/addons21/1322529746/ankihub_client/models.py", line 55, in <module>
class NoteInfo(DataClassJSONMixinWithConfig):
...<12 lines>...
)
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/mixins/dict.py", line 26, in __init_subclass__
compile_mixin_unpacker(cls, **builder_params["unpacker"])
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/core/meta/mixin.py", line 49, in compile_mixin_unpacker
builder.add_unpack_method()
~~~~~~~~~~~~~~~~~~~~~~~~~^^
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/core/meta/code/builder.py", line 584, in add_unpack_method
self._add_unpack_method_lines(method_name)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/core/meta/code/builder.py", line 489, in _add_unpack_method_lines
).build(
~~~~~^
fname=fname,
^^^^^^^^^^^^
...<2 lines>...
alias=alias,
^^^^^^^^^^^^
)
^
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/core/meta/code/builder.py", line 1330, in build
unpacked_value = UnpackerRegistry.get(
ValueSpec(
...<8 lines>...
)
)
File "/home/user/.local/share/Anki2/addons21/1322529746/lib/mashumaro/core/meta/types/common.py", line 225, in get
raise UnserializableField(
spec.field_ctx.name, spec.type, spec.builder.cls
)
mashumaro.exceptions.UnserializableField: Field "tags" of type Optional[List[str]] in NoteInfo is not serializable
Search
Found 0 results for âtags:official Python 3.14 mashumaro UnserializableField tags Optional[List[str]] NoteInfo AnkiHub category: Support order:latest_topic max_posts:5 status:openâ
Thanks for reporting this and for including the full traceback + environment detailsâthatâs very helpful.
Youâre exactly right: this is an incompatibility between the AnkiHub add-onâs bundled mashumaro version and Python 3.14, which is whatâs causing the UnserializableField error for tags: Optional[List[str]] in NoteInfo.
At the moment:
The AnkiHub add-on is primarily tested against the official Anki builds, which currently ship with Python 3.9/3.10 (depending on platform and version), not 3.14.
Running the add-on on a system-packaged Anki with Python 3.14 (like Arch Linux) is therefore not officially supported yet, and issues like this can occur until we explicitly update and test dependencies such as mashumaro.
What you can do right now
Use the official Anki build (recommended workaround for now)
Download from https://apps.ankiweb.net and run Anki from that build instead of the Arch package. The AnkiHub add-on should work there without this Python 3.14 issue.
Stay on an older Python/Anki package (if your distro makes that easy)
Some users pin or downgrade to a distro Anki build that uses an earlier Python until add-ons catch up.
About updating mashumaro
Your request to update mashumaro is totally reasonable, and this is something weâll need to do (along with testing on newer Python versions) before we can claim compatibility with Python 3.14-based builds. I donât have the ability to patch the codebase directly from here, but:
Iâve noted this as an incompatibility with Python 3.14 / Arch Linux build that will likely require a mashumaro update and possibly code adjustments for the tags: Optional[List[str]] handling.
Until that happens, the only reliable way to use AnkiHub on your setup is to switch to the official Anki build or a distro build that uses an older Python version.
If youâre willing, it would also help to mention in the topic whether:
Other add-ons are working fine under your Arch build, and
Whether this only happens with AnkiHub enabled (i.e., no issues when itâs disabled).
That info can make it easier for the devs to reproduce and prioritize the fix.
You are running into a compatibility issue caused by your systemâs Python version (3.14.3).
The Anki package in the standard Arch repositories relies on this system-wide Python. The AnkiHub add-on uses a library (mashumaro) that has not yet been updated to support Python 3.14 structure, which is why itâs failing to load.
To fix this, we highly recommend using the official Anki build, which comes bundled with its own isolated, officially supported Python environment.
Thank you for your reply. Iâd like to keep using the Anki and Python version provided by my distribution. Since the same developer team now maintains both Anki and the AnkiHub addâon, itâs reasonable to expect the addâon to work with the same Python versions that Anki supports.
Could you provide guidance on how to upgrade mashumaro on my existing installation? Iâm happy to update the libraries locally and test the result on my own system. I appreciate your help.
Yes, itâs definitely a gradual transition, and some things just take a bit of time. Even though Anki and AnkiHub are closely connected, we still use separate support channels depending on the type of issue.
For core technical issues, we highly recommend reaching out on the official Anki forums (Anki - Anki Forums), as youâll be able to get much better support for specific technical problems there. Unfortunately, Iâm not a Linux user myself, so I canât offer much direct help with this one!
Anki is not officially supported on Python 3.14 yet. The official packages use Python 3.13 and thatâs the version Anki maintainers work with on daily basis currently: anki/.python-version at main ¡ ankitects/anki ¡ GitHub
Thanks, I didnât know that only 3.13 is supported. Iâm happy to report that Anki itself, plus all of my other extensions, work on 3.14. I was also able to make AnkiHub work on 3.14 with some AI assistance.
Problem
Anki stores addons in directories named by their numeric addon ID (e.g., 1322529746/ ). When Python imports from this directory, the module name becomes 1322529746.ankihub_client.models .
The issue is that mashumaroâs code generator creates type references like typing.List[1322529746.ankihub_client.models.Field] , which is invalid Python syntax because identifiers canât start with a digit (according to AI).
This is the culprit at lines 340-341 in mashumaro/core/meta/helpers.py:
When short==False , itâs using typ.__module__ directly, which for classes inside the addon is 1322529746.ankihub_client.models (the numeric addon ID is part of the module name).
Workaround
Replace those lines with:
if short:
return typ.__qualname__ # type: ignore
else:
module_name = typ.__module__ # Strip numeric addon ID prefix (e.g., "1322529746.ankihub_client" -> "ankihub_client")
parts = module_name.split(".")
if parts and parts[0].isdigit():
module_name = ".".join(parts[1:])
return f"{module_name}.{typ.__qualname__}" # type: ignore
Clearly this is not a stable solution because that involves patching the mashumaro library, however I wanted to point this out as a workaround for anyone with the same issue.
Support order:latest_topic max_posts:5 status:openâ