live2d-py

Docker Build Version Python Version CMake C++17 CsmSDK

English README

注意：本仓库不包含 Live2D Cubism Core 及 Framework（受许可限制），源码编译时需自行从 Live2D官网下载。

使用 Python 直接加载和操作 Live2D 模型，不通过 Web Engine 等间接手段进行渲染。

基于 Python C Extension 对 Live2D Native SDK (C++) 进行了封装。理论上，只要配置好 OpenGL 上下文，可在 Python 中将 live2d 绘制在任何基于 OpenGL 的窗口。

代码使用示例：examples

详细使用文档：Wiki

修改和开发：CONTRIBUTING

兼容UI库

理论上兼容所有能使用 OpenGL 进行绘制的UI库： Pygame / PyQt5 / PySide2 / PySide6 / GLFW / pyopengltk / FreeGlut / Qfluentwidgets ...

支持功能

加载模型：Cubism 2.1 和 Cubism 3.0 及以上版本
视线跟踪
点击交互
动作播放回调
口型同步
模型各部分参数控制
各部件透明度控制
精确到部件的点击检测

兼容性

Cubism Live2D 版本

`live2d-py`	支持的live2d模型	实现
`live2d.v2`	Cubism 2.1 以及更早的版本	纯 Python 实现
`live2d.v2cpp`	Cubism 2.1 以及更早的版本	C++ 移植 (高性能)
`live2d.v3`	Cubism 3.0 及以上版本	Python C Extension 封装

推荐使用 live2d.v2cpp 替代 live2d.v2 以获得更好的性能。API 完全兼容，只需将 import live2d.v2 as live2d 替换为 import live2d.v2cpp as live2d。

Python 版本及平台

✅: 可用, 支持, 已通过

❓: 尚未测试

🚧, ❌: 编译期问题或平台兼容性问题待解决

Platform	Python Version	`live2d.v2`	`live2d.v2cpp`	`live2d.v3`	PyPI
macOS arm64	`>=3.11`	✅	✅	✅	✅
Windows x64	`>=3.11`	✅	✅	✅	✅
Linux x64	`>=3.11`	✅	✅	✅	❌

注：

Cubism 2.X 导出的模型：文件名格式常为 XXX.moc，XXX.model.json，XXX.mtn
Cubism 3.0 及以上导出的模型：文件名格式常为 XXX.moc3，XXX.model3.json, XXX.motion3.json

使用说明

在 Release 中下载对应版本的 whl 文件并安装（推荐）

pip install live2d_py-0.X.X-cpXXX-cpXXX-win_amd64.whl

通过 PyPI 安装

pip install live2d-py

从源码构建，参考安装#源码构建

示例

简易面捕

源码见 main_facial_bind.py

面捕-期末周破防

基于 live2d-py C 模块及 Qt 开发的 Live2DViewer

Live2DViewer

多模型加载

源码见 main_glfw_four_model.py

multi_model

添加背景

源码见 main_pygame_background.py

background

模型变换 & 口型同步音频 & 点击测试

源码见 main_glfw.py

完整用例

模型整体透明度示例

源码见 main_pyqt5_canvas_opacity.py

opacity

鸣谢

特别感谢以下用户为本项目提供的帮助和支持: 96bearli, Ovizro, AnyaCoder, jahtim, Honghe, RobertMeow, LUORANCHENG, TinyKiecoo, Barracuda72, GuangChen2333, makabakadot, thynetruly, mastwet, KyvYang, @Mozilla88, @CooperWang0912, @minghf85

非常感谢以下项目及其贡献者们的帮助：

CubismNativeSamples (live2d.v3)

Cubism2 Web SDK (live2d.v2)

de4js（JavaScript 反混淆工具）

JsConvert (Javascript 转 Python 工具)

D2Evil (moc 文件分析)

facial-landmarks-for-cubism （面捕参考）

Live2D 模型:

Release files for live2d-py 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for live2d-py 0.8.0
File	Interpreter	ABI	Platform	Reset
live2d_py-0.8.0-cp311-abi3-win_amd64.whl 491.5 kB Sep 24, 2026	CPython 3.11	abi3	Windows x86-64	Details
live2d_py-0.8.0-cp311-abi3-macosx_26_0_universal2.whl 587.3 kB Sep 24, 2026	CPython 3.11	abi3	macOS 26.0+ universal2 (ARM64, x86-64)	Details

Total release size: 1.1 MB

Release files / live2d_py-0.8.0-cp311-abi3-win_amd64.whl

Download URL	live2d_py-0.8.0-cp311-abi3-win_amd64.whl
Size	491.5 kB
Tags	CPython 3.11 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`0323a089b7d3efa57c042d2d82f136068f59274ade92fe1125057cd926fe4dca`
BLAKE2b-256 checksum How to use checksums	`4d5dfb3af900ae3aa9973443fb11938a244c38b88020b838bb6d800da17fe827`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.9`

Release files / live2d_py-0.8.0-cp311-abi3-macosx_26_0_universal2.whl

Download URL	live2d_py-0.8.0-cp311-abi3-macosx_26_0_universal2.whl
Size	587.3 kB
Tags	CPython 3.11 abi3 macOS 26.0+ universal2 (ARM64, x86-64)
SHA-256 checksum How to use checksums	`b3072237d529f226eed31540722cb9cd0310b33475c831410558c15f5e06912b`
BLAKE2b-256 checksum How to use checksums	`8dea8c1d094f656785fb7c1a392bf877e1a15ff95f4fc2711c6e30a62a72a587`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.9`