Skip to content
Arkueid edited this page Sep 29, 2026 · 14 revisions

本 Wiki 编辑权限对所有人开放,欢迎大家前来编写修改使用说明、分享使用技巧、更多玩法~

English version: Home.en

live2d-py 是一个 Python C Extension 实现的 Live2D 库。

live2d-py 使用 CMake 构建项目,主要模块包括:OpenGL API 管理库 Glad、 Cubism Live2D 官方发布的 Core 和 Native Framework,基于官方 Sample 魔改的 Main 模块,以及 Python 对前三者的封装 Wrapper 模块。

本项目的主要目的是为 Python 提供 Live2D 渲染功能。

此外,也可将本项目中 Python 封装的部分剔除,在仅使用其 C 模块(Core、Framework、Main)的基础上进行二次开发,编写基于 C/C++ 的 Live2D 应用或者为其他编程语言(如 alive2d)写 C 绑定库,提供 Live2D 渲染功能。

使用说明

live2d模块只为单线程使用设计,请勿在多个线程中操作live2d.Model

自 1.0.0 起,Cubism 2.1 与 Cubism 3.0(含 4.0)模型由同一个类 live2d.Model 加载,加载时根据模型 json 自动识别版本:

import live2d

live2d.init()

model = live2d.Model()
model.LoadModelJson("path/to/model3.json")  # Cubism 3.0+ 模型(.model3.json)
# 或
model.LoadModelJson("path/to/model.json")   # Cubism 2.1 模型(.model.json)

print(model.Version())   # 3 或 2
print(model.IsV3())      # True / False
  • Cubism 2.1 模型由 C++ 移植(v2cpp)实现,性能远优于纯 Python 版本
  • 纯 Python 的 live2d.v2 已废弃(导入时打印提示),请改用 live2d.Model
  • 完整接口提示见 package/live2d/_live2d.pyi

具体与图形库结合的用例示例见 examples 文件夹。

Python 版本及平台

✅: 可用, 支持, 已通过

❓: 尚未测试

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

Platform Python Version live2d.Model 构建状态 PyPI
MacOS arm64 >=3.11 ✅ ✅ ✅
Windows x64 >=3.11 ✅ ✅ ✅
Ubuntu/Arch Linux, x64 >=3.11 ✅ ✅ ✅

注:

  • Python 版本要求 >=3.11
  • Cubism 2.X 导出的模型:文件名格式常为 XXX.moc,XXX.model.json,XXX.mtn
  • Cubism 3.0 及以上导出的模型:文件名格式常为 XXX.moc3,XXX.model3.json, XXX.motion3.json
  • 本仓库包含 Cubism Core 及 Framework(位于 Live2D/),无需自行下载 SDK

页面导航

Clone this wiki locally