Repository navigation
Python 3.14: compatibility issue with default lazy annotations #153
Description
Highlighting the Python 3.14 compatibility requirements:
- base any data model classes passed to the SDK on Pydantic rather than
lmstudio.BaseModel; or - specify
from __future__ import annotationsto use string annotations instead of lazy ones (sincemsgspechandles those)
lmstudio-python is affected by msgspec/msgspec#847, so running on Python 3.14+ currently requires the use of from __future__ import annotations when defining structured response formats based on lmstudio.BaseModel.
The main SDK schema export classes already used string annotations to avoid forward referencing problems, so the PR adding 3.14 to CI (#154) works around the issue by also adding from __future__ import annotations to the affected test modules.
Client applications relying on Pydantic for their data model classes won't be affected (beyond needing to update to Pydantic 2.12.0a1 or later), but those relying on lmstudio.BaseModel to define their structured response formats will currently also need to use from __future__ import annotations for their struct fields to actually get defined.
Activity
[-]Python 3.14rc2: `msgspec` incompatibility with default lazy annotations[/-][+]Python 3.14rc2: compatibility issue with default lazy annotations[/+]baonudesifeizhai commentedon Aug 22, 2025
i will try to fix it
ncoghlan commentedon Aug 22, 2025
@baonudesifeizhai This isn't one we can really workaround at the SDK level (see msgspec/msgspec#847 (comment) for a couple of the things I already tried and found wouldn't work).
There is still a month and a half before Python 3.14 final is released, and demand for 3.14 support isn't likely to be immediate, so we have time to wait for a new
msgspecrelease with the compatibility fix incorporated.One thing I am currently doing is confirming that the submitted compatibility fix PR does solve the problem for us.
ncoghlan commentedon Aug 22, 2025
Confirmed with c20473c that pulling in the msgspec/msgspec#852 changes resolves the structured response test failures without needing the
from __future__ import annotationsworkaround.ncoghlan commentedon Sep 8, 2025
Hmm, re-reading my comment on the
msgspecissue, I'm not sure I ever tried__init_subclass__as a potential workaround. I'll see if using that to eagerly populate__annotations__at class definition time (before callingsuper().__init_subclass__works).I think I tried it and it didn't work, but I didn't record that experiment if so.
Edit: experiment has been (re)tried in #158, and it doesn't work (which makes me suspect the "didn't record the result" situation, rather than "didn't try it at all")
Python 3.14: implicitly eager Struct annotations
[-]Python 3.14rc2: compatibility issue with default lazy annotations[/-][+]Python 3.14: compatibility issue with default lazy annotations[/+]ncoghlan commentedon Oct 17, 2025
msgspec/msgspec#875 (comment) indicates full Python 3.14 support in
msgspecshouldn't be too far away.ofek commentedon Nov 24, 2025
msgspec support for 3.14 has been released https://github.com/jcrist/msgspec/releases/tag/0.20.0