live2d-py renders Live2D avatars from Python without a web engine

Direct rendering, not a web engine in a window

The repository is described as a Live2D library for Python with a C++ implementation, supporting model loading, lip sync, basic face rigging and precise click testing. The Chinese README makes the architectural point in one line, that you use Python to load and operate Live2D models directly, without going through an indirect route such as a web engine for rendering.

The implementation is a Python C extension wrapping the Live2D Native SDK in C++, and the README's claim about that is that in theory, as long as you configure an OpenGL context, you can draw live2d in any OpenGL based window from Python.

That claim is why the compatible UI library list is as long as it is: Pygame, PyQt5, PySide2, PySide6, GLFW, pyopengltk, FreeGlut and Qfluentwidgets are all named, and the wording is that it is theoretically compatible with all UI libraries that can draw with OpenGL.

The primary language of the repository is C++, the licence is MIT, the last push was on 2026-10-18, and the releases are v1.0.0 from 2026-09-30, v0.8.1 from 2026-09-26 and a v0.8.0.9-alpha from 2026-09-24, so the project only recently reached a 1.0 tag after a long alpha period.

The Cubism Core is licensed separately and is not in the repository

The first thing the README tells you, in a bold note, is that this repository does not include the Live2D Cubism Core and Framework, because of licensing restrictions, and that when you build from source you have to download them yourself from Live2D's official site.

The `setup.py` file in the repository spells out the same point in English, and the disclaimer is worth reading in full because it defines what you are allowed to do with the result:

1. Copyright Ownership: Live2D Cubism Core library is the exclusive property of Live2D Inc.
   All intellectual property rights (including copyright) belong to Live2D Inc.
    
2. Distribution Restriction: Under Live2D's official Terms of Service, third parties are 
   prohibited from distributing/sharing Cubism Core files. This script only provides an 
   "auto-guided download" function and does NOT store or forward any Core files.
    
3. Compliance Requirement: You must adhere to the Live2D Cubism SDK End User License 
   Agreement (EULA). Core library usage is restricted to legal personal/commercial projects 
    
4. Liability Waiver: This script is provided as a convenience tool only. It bears no 
   responsibility for the integrity or compatibility of Core files. Any compliance issues 
   arising from the use of this script are the sole responsibility of the user.

The practical consequence is that `pip install live2d-py` gives you the wrapper and the bindings, and the licensed core is your responsibility. The README lists the official acquisition channels, the Cubism official website, the developer documentation and the licence agreement page, and the setup script provides an auto-guided download rather than shipping the files itself.

This is not legal advice. The point for an engineer is that the licence boundary sits between this repository and the SDK, and the build fails or misbehaves without the part you are expected to fetch yourself.

Two model APIs, and the README tells you which to use

There are two ways to reach a model, and the compatibility table distinguishes them.

`live2d.v2.Model` is a pure Python implementation and supports Cubism 2.1 and earlier models. `live2d.Model` supports Cubism 2.1 and earlier as well as Cubism 3.0 and above, and it is implemented as a C++ port of the Cubism 2.X WebSDK, with a Python C extension wrapping the Cubism Native SDK.

The README recommends `live2d.Model` in bold, and the reasoning is visible in the table: the newer API is the one that can load a Cubism 3.0 model, and the badge set in the README header shows the CsmSDK version required, 5.x release r.5.

The model file names differ between the two generations, and the README gives them explicitly. A model exported from Cubism 2.X is usually named `XXX.moc`, `XXX.model.json` and `XXX.mtn`, while a model exported from Cubism 3.0 or above is usually named `XXX.moc3`, `XXX.model3.json` and `XXX.motion3.json`.

So the first thing to check when a model fails to load is the extension, since a Cubism 3 model handed to the v2 API is a naming mismatch before it is a code bug.

What the feature list actually covers

The supported feature list is short and specific.

Model loading covers Cubism 2.1 and Cubism 3.0 and above. There is gaze tracking, click interaction, and motion playback callbacks. There is lip sync, which is the feature that makes an avatar usable in a talking application. There is control of the parameters of the individual model parts, and control of the opacity of each part. And there is click detection that is precise down to the part, which is different from a general hit test on the model as a whole.

That last item is what the example set demonstrates. `main_glfw.py` is described as covering model transforms, lip sync audio and click testing together, `main_pyqt5_canvas_opacity.py` covers opacity for the model as a whole, `main_glfw_four_model.py` covers loading several models at once, and `main_pygame_background.py` covers adding a background behind the avatar.

The face capture example, `main_facial_bind.py`, is the one that shows the rigging side, and the repository also ships a Live2DViewer application built on the live2d-py C module and Qt.

Everything in the examples directory is Python, with files for Pygame, PyQt5, PyQt6, PySide2, PySide6, Tkinter, GLFW, Vulkan and a MediaPipe capture helper, plus `motion_fix.py` and a `resources.py` module. The wiki is linked as the detailed usage documentation.

Install from a wheel, from PyPI, or from source

The README gives three routes, and recommends the wheel.

From the releases page, download the matching `whl` file and install it:

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

Or install from PyPI:

pip install live2d-py

Or build from source, following the wiki page on source builds.

The version and platform matrix explains why the wheel is the recommended route. Python 3.11 and later is required, CMake 3.26 or newer, and C++17. The availability table marks macOS arm64, Windows x64 and Linux x64 as all available for `live2d.v2`, `live2d.v2cpp` and `live2d.v3`, and marks PyPI as available for all three. The table also has a legend for states, available and passed, not yet tested, and compile time or platform compatibility issues to be resolved.

The continuous integration side is broader than the wheel matrix, with separate workflows for Windows, macOS, Linux x86_64 manylinux, Linux ARM64 manylinux and a separate distribution for the Live2DViewer, so the viewer is built in the same pipeline as the library.

The Python dependency set is small, the SDK is not

The project metadata for the package is short, and the dependencies are ordinary:

[build-system]
requires = ["setuptools>=70.1"]
build-backend = "setuptools.build_meta"

[project]
requires-python = ">=3.11"
dynamic = ["version"]
license = "MIT"
name = "live2d-py"
dependencies = [
    "pyopengl",
    "pillow",
    "numpy"
]

So the Python side pulls in pyopengl for the context, Pillow for images and NumPy for arrays, and nothing else. The version is dynamic, the licence is MIT, the description is a non-web Live2D library for Python, and the project links its own documentation site and repository.

The repository layout reinforces the division. There is `Live2D/` for the SDK integration, `Wrapper/` for the binding layer, `Resources/` for assets, `package/` for the wheel build, `Live2DViewer/` for the Qt viewer, plus `examples/`, `tests/`, `docs/`, `wiki/`, `cmake/`, `setup.py`, `pyproject.toml` and a `MANIFEST.in`.

That layout is the practical answer to the licensing question. The parts that are yours to redistribute are in the repository, the parts that are not are the Cubism Core and Framework, and the build pulls them in from where you obtained them.

Editorial conclusion

Adopt live2d-py when you need a Live2D avatar rendered by a native Python application rather than a web view, and when you already have the right to use the Cubism SDK. Do not adopt it expecting the Cubism Core to come with it, since the repository deliberately excludes it. Verify first that you have downloaded the Cubism Core and Framework from Live2D's own site for the version you target, that the model format matches the API you pick, since Cubism 2.x and Cubism 3.0 use different file names, and that your platform and Python version match the availability matrix, since the wheels are built for Python 3.11 and later on macOS arm64, Windows x64 and Linux x64.

Frequently asked questions

Official sources

1. EasyLive2D/live2d-py on GitHub
2. License: MIT
3. Project website
4. README
5. Releases