Repository navigation
bithuman: resolve the SDK on Python 3.10 and 3.14 again - #7280
Merged
Merged
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
davidzhao
reviewed
Sep 14, 2026
| # stays wide so platforms 2.x dropped (Windows, x86_64 macOS, macOS < 14) can | ||
| # still resolve the 1.x line, which satisfies everything avatar.py calls. | ||
| # bithuman 2.8.1+ ships wheels for every Python livekit-agents supports (3.10 | ||
| # through 3.14), so the dependency no longer needs a python_version marker. The |
Member
There was a problem hiding this comment.
remove bithuman comment here?
chenghao-mou
approved these changes
Sep 15, 2026
The python_version marker on the bithuman dependency was added in #6561 and #6614 because bithuman 2.3.11 through 2.8.0 only built for Python 3.11-3.13. bithuman 2.8.1 (August 2026) restored cp310 and cp314 wheels and declares >=3.10,<3.15, so the marker now wrongly leaves the plugin without its SDK on 3.10 and 3.14. Drop the marker, add the 3.14 classifier, and move the lock from 2.7.0 to 2.9.0, the newest 2.x with wheels for every supported interpreter.
Review feedback on the marker removal. print_unsupported_python existed only to explain the SDK's absence on the versions the marker excluded. With the marker gone it fires on any ImportError and blames the interpreter for unrelated failures, so both it and the two try/except wrappers go, letting the real error propagate. Doing that exposed a pre-existing bug the wrapper had been swallowing: avatar.py imports PIL at module scope but the package never declared pillow, so the import failed on every Python version, 3.13 included. Declare it the way livekit-plugins-lemonslice does. Also drop the dependency comment, which described a marker that no longer exists.
theomonnom
force-pushed
the
theo/bithuman-py314
branch
from
September 15, 2026 21:50
fbeca9b to
9889f85
Compare
sgu-bithuman
added a commit
to bithuman-product/public-docs
that referenced
this pull request
Sep 19, 2026
…n, and the pages said so only half
The plugin is LiveKit's package, published from github.com/livekit/agents. Both
its failure modes are ours to document even though neither is ours to fix.
Driven today in five fresh venvs, PyPI 1.8.2, nothing else installed:
py3.11/3.12/3.13 pip ok, then ModuleNotFoundError: No module named 'PIL'
(avatar.py:16 `from PIL import Image`, never declared)
py3.10/3.14 pip ok, NO bithuman installed at all, then
ModuleNotFoundError: No module named 'cv2'
(the marker `python_version >= "3.11" and < "3.14"`, now
stale — bithuman 2.11.3 publishes cp310 AND cp314)
`/guides/deploy-livekit` already said `pip install livekit-plugins-bithuman
pillow`, which is why its reader was safe — on 3.11-3.13. It did not say that
the SAME line still fails on 3.10 and 3.14, where the missing module is `cv2`,
not `PIL`. Measured, and now a table on the page:
pip install livekit-plugins-bithuman 3.11-3.13 PIL · 3.10/3.14 cv2
… pillow 3.11-3.13 works · 3.10/3.14 cv2
… pillow bithuman 3.11-3.13 works · 3.10/3.14 works
Naming `bithuman` yourself is the whole 3.10/3.14 workaround: the wheel installs
and imports cleanly on both, so the marker is stale rather than protective.
★NO UPSTREAM PR IS NEEDED — BOTH FIXES ARE ALREADY MERGED AND MERELY
UNRELEASED. livekit/agents#7280 (`068971fe`, 2026-09-15 15:08 -0700) adds
`pillow>=10.3.0` and drops the marker, about four hours after the 1.8.2 release
commit was cut. Verified by cloning the repo, applying the proposed patch on top
of origin/main (`e5024c76`) and getting an EMPTY diff, then building a wheel
from main and importing it on 3.10, 3.12 and 3.14 — ok on all three. The ask to
LiveKit is a patch release, not a patch. Both pages say so now, so a reader
knows the workarounds have an expiry.
Also: the plugin release is 1.8.2, not 1.8.1, and `bithuman<3` resolves 2.11.3
today, not 2.3.4. Both were named on /sdk/livekit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NoF6sY6vvij3uDYUxnyCri
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
python_version >= '3.11' and python_version < '3.14'marker on thebithumandependency (#6561, #6614) was correct when bithuman 2.3.11 through 2.8.0 only shipped cp311–cp313 wheels. bithuman 2.8.1 (2026-08-01) restored cp310 and cp314 wheels and declaresRequires-Python: >=3.10,<3.15, and every release since (2.9.0, 3.x) does the same. The marker now leaves the plugin installed without its SDK on Python 3.10 and 3.14.Changes:
bithuman>=0.5.25,<3.Programming Language :: Python :: 3.14classifier, matchinglivekit-agents.uv lock --upgrade-package bithuman: 2.7.0 → 2.9.0, the newest 2.x with wheels for every supported interpreter. 2.9.0 dropped itsnetworkxdependency, which is why that package leaves the lock.print_unsupported_pythonand the twotry/except ImportErrorwrappers that called it. That helper existed only to explain the SDK's absence on the versions the marker excluded; with the marker gone it fires on anyImportErrorand blames the interpreter for unrelated failures.pillow>=10.3.0.Not changed: the
<3upper bound. bithuman 3.0.0 shipped on 2026-09-07 and has not been checked againstavatar.py, so that belongs in its own PR.The pillow fix
Removing the wrapper exposed a pre-existing bug it had been swallowing.
avatar.pyimportsPILat module scope, but the package never declaredpillow, so importing the plugin raisedModuleNotFoundError: No module named 'PIL'on every Python version unless something else in the environment happened to pull Pillow in. Reproduced against unmodifiedmainon CPython 3.13, a fully supported version:The old wrapper caught this, called
print_unsupported_python(), which printed nothing on 3.13 and re-raised — which is exactly the misdiagnosis the helper's removal is meant to avoid.livekit-plugins-lemonslice, the only other plugin importing PIL, declarespillow>=10.3.0; this matches it.Verification
uv pip installof the plugin on CPython 3.14.7 and 3.10.18: both resolvebithuman==2.9.0andpillow==12.3.0, andfrom livekit.plugins.bithuman import AvatarSession, BitHumanExceptionsucceeds on both.uv lock --checkpasses;ruff checkandruff format --checkpass.Reported in Slack: https://live-kit.slack.com/archives/C05P6DRC6MV/p1789407534492229
🤖 Generated with Claude Code