VRM Add-on for Blender is both a UI add-on and a headless Python package

Two installation paths and a PyPI package

VRM Add-on for Blender adds VRM import, export and editing capabilities to Blender, and it also provides an API for automation via Python scripts.

The download section splits by Blender version, and the split is real rather than cosmetic.

- Blender 4.2 or later, download from Blender Preferences - Blender 4.2 or later, download from a web browser - Blender 2.93 to 4.1 - Python package on PyPI (bpy-vrm-format)

The 4.2 split is the extension system change in Blender, where add-ons moved to a different installation and packaging model. Before 4.2 you install by copying files into the addons directory, and from 4.2 you install through the Preferences interface or download an extension package from the browser. The project supports both, and the repository description states the range as Blender 2.93 to 5.2.

The PyPI route is the one that matters for a pipeline. The package is bpy-vrm-format, and the pyproject.toml gives the details.

[project]
name = "bpy-vrm-format"
version = "4.10.2"
description = "VRM import, export, and editing capabilities"
license = { text = "SPDX-License-Identifier: MIT OR GPL-3.0-or-later" }
dependencies = ["bpy"]

So the same code is both a Blender add-on and a Python package that depends on bpy, the Blender Python module. The version number is shared between the add-on and the package, 4.10.2, and the authors are listed as Isamu Mogi and iCyP, which is the same iCyP who wrote the original project.

The build backend is uv_build with a requirement of uv_build at 0.12.1 or newer and below 0.13.0, and the dependency list for development includes bpy pinned per platform and Python version, bpy 3.6 for Python 3.10 on Windows, macOS and Linux. The dev group also pulls in a package called bpy-vrm-format-benchmarks, which is a separate distribution of the benchmark suite, so the benchmarks are importable rather than being a script inside the main tree.

A project with a history and a handover

The Overview section carries the one sentence that explains the project's character.

This add-on adds VRM-related functionality to Blender, including importing and exporting VRM files, adding VRM Humanoid, and configuring MToon shaders. Bug reports, feature requests, pull requests, and contributions are welcome. I have taken over development after Version 0.79 from the original author, @iCyP.

So this is a maintained fork of a maintained project, with a stated handover point. The original add-on was VRM_IMPORTER_for_Blender2_8 and its 0.79 release is the boundary. The current version numbering, 4.10.x, is on a different scale entirely, which tells you the project has been re-versioned rather than continuing the original sequence.

The features are the three that a VRM workflow actually needs. Import, so a model arrives in Blender with its structure. Export, so it can leave with the structure intact. And editing, which for VRM means the humanoid armature and the MToon material setup, since a VRM file is not just a mesh, it is a mesh plus a rig plus a material model plus metadata, and the last two are what the tools exist to preserve.

The tutorial table in the README maps to that structure. There is Create Simple VRM and Create Humanoid VRM for the two levels of model, Create Physics-Based Material and Create Anime-Style Material for the two material models, and VRM Animation for the animation side. Physics-based means a conventional glTF metallic-roughness material, and anime-style means MToon, which is VRM's own cel shading model. The addon configures MToon shaders, which is the harder half, because MToon is a toon rendering model rather than a physically based one, and Blender's material system does not have it natively.

The Automation with Python Scripts tutorial and the Development How-To sit at the end of the same table, which is a fair ordering because the scripting API is what a production pipeline uses.

The add-on source is an ordinary directory you can symlink

The Development section explains the development setup in a way that is worth reading, because it reveals how the add-on is structured.

The src/io_scene_vrm folder contains the main add-on code. By creating a symbolic link to this folder in Blender's user_default or addons directory, you can install the development source code as an add-on in Blender, making it easy to test changes efficiently.

The directory name is the key detail. io_scene_vrm follows Blender's own naming convention for an import and export format, where the io_scene_ prefix marks a format handler, so the add-on registers itself as a file format in Blender's import and export menus. That convention is what makes the add-on appear where a user expects it rather than as a generic script, and it is also why the folder can be symlinked into place, because Blender loads it by path.

The instructions for the development link are given per Blender version, and the Linux example begins with a version variable.

blender_version=4.5
mkdir -p "$HOME/.config/blen

The directory it creates is the per-version Blender configuration directory, so the path differs for each Blender version you have installed. The rest of the instructions cover the other platforms and the 4.2 and later case, where the addons directory moved.

The README points at a separate development environment setup documentation for advanced tasks such as running tests, and the repository top level listing shows the surrounding machinery. There is a .devcontainer/ directory and a devcontainer script in package.json, a tests/ directory, a benchmarks/ directory, a docs/ directory built with VitePress, an examples/ directory with three subdirectories, a typings/ directory, and a tools/ directory full of small Node scripts.

Those tool scripts are worth noting, because they show a project that automates its own checks. There is a vrm-validator script, a pyright wrapper, an update-changelog script, and a docs:copy-docs-to-src script that copies the documentation into the source tree, which is how the add-on can ship the same docs that the site publishes.

A JavaScript toolchain wrapped around a Python add-on

The root package.json is unusual for a Blender add-on, and looking at it explains why.

{
  "name": "vrm-addon-for-blender",
  "private": true,
  "type": "module",
  "scripts": {
    "docs:build": "vitepress build docs",
    "pyright": "uv run -- node --import tsx ./tools/pyright.cts --warnings",
    "vrm-validator": "node --import tsx ./tools/vrm_validator.ts",
    "update-changelog": "node --import tsx ./tools/update_changelog.ts"
  },
  "engines": {
    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
  },
  "packageManager": "[email protected]"
}

The package is private, it is an ES module project, and every script is a Node script that shells into a Python tool. The pyright script runs uv run, which is the Python package manager, to execute a TypeScript file that drives the Python type checker with the warnings flag. The vrm-validator script runs the VRM validator, and the devDependency is gltf-validator at 2.0.0-dev.3.10, which is the Khronos glTF validator that VRM is built on.

So the project runs its own validator against its own output. That is the kind of self check that matters for a format add-on, because a VRM file that passes the validator is known to be well formed against the glTF schema, and the validator is the same one other tools use.

The other dev dependencies are equally deliberate. pyright at 1.1.414 and starry-bpy-typings, which is a set of type stubs for the bpy module, because bpy has no built in types and Blender's Python API is large and dynamic. The types are what make a type checker useful on a Blender add-on at all.

And the Python side has the same care. The pyproject.toml configures black and isort with extend-exclude set to exclude everything, with the comments Please use Ruff instead, and mypy with exclude set to the whole tree and ignore_errors true, with the comment Please use pyright instead. The Python linters are configured to do nothing because the type checking and linting are done by the Node-driven tools, and Ruff at the latest version is in the dev dependency group. codespell has a skip list that includes the Unity test resources, and a .trivyignore and a .actrc at the root are there for the security scanning and the action runner.

Where VRM Add-on for Blender is the wrong choice

The first wrong case is a one-off import. If you have a VRM file and want a mesh in Blender and do not care about the rig or the MToon material, the add-on is more than you need, and the import is a small part of what this project does. The emphasis on humanoid setup, MToon shader configuration and round-trip export is aimed at people building avatars, not at people extracting geometry.

The second wrong case is a team that needs a stable, versioned add-on. The releases come out frequently, v4.10.0, v4.10.1 and v4.10.2 on three consecutive days in October 2026, and the dependency set is wide. The Blender version range spans 2.93 to 5.2, which is good for reach but means you are likely to run a version combination the project has moved past, and the add-on has to be reinstalled when Blender changes its extension model.

The third wrong case is a pipeline that cannot use bpy. The PyPI package depends on bpy, which means it needs a Blender Python environment, so a headless conversion running on a build server still needs Blender installed, and the headless Blender invocation is a separate piece of setup that the documentation has to cover rather than the package.

The fourth wrong case is a project that needs a different avatar format with the same rig. VRM is a specific format, and the export writes VRM. If the target pipeline is glTF with a different avatar convention, the importer is still useful but the exporter is not, and the metadata that VRM carries has no equivalent elsewhere.

How it differs from the original VRM importer

The comparison worth making is with the project it was forked from, since the README says the development was taken over after version 0.79 of VRM_IMPORTER_for_Blender2_8.

The original was a Blender 2.8 era add-on, and its name reflects that, the 2_8 in the repository name. It was built for a Blender whose add-on system, Python version and material node API were all different from today's. A fork of that code in 2026 could not simply continue, and the version jump from 0.79 to 4.x signals a rewrite or a large rebase rather than an increment.

The difference in approach is the modern Blender extension packaging, the 4.2 and later install path, which is a different distribution mechanism with a different trust model, since extensions are signed and published through Blender's own system rather than being copied into a folder. The project supports both paths, which is what a fork with an existing user base has to do.

The second difference is the surrounding engineering. The original was a Python add-on in a Python repository. This has a Node toolchain with VitePress for the documentation, a devcontainer, a devDependency on the glTF validator, type stubs for bpy, a Python linter and type checker invoked through Node, and a release process driven by release-please with a .release-please-manifest.json and a release-please-config.json. The release cadence of the current project, several releases a week judging by the version numbers, is not sustainable without that automation.

The third difference is the scope of the material support. The current project documents physics-based and anime-style materials as separate tutorials, an API for scripting, and a VRM 1.0 export hook and import hook in the examples directory, so the format has a second version in the pipeline and the examples show how to hook into it.

Editorial conclusion

VRM Add-on for Blender fits an artist who needs to bring a VRM avatar into Blender and put it back out with the humanoid rig and MToon materials intact, and it fits a pipeline engineer who needs the conversion to run headless from a script rather than through the interface. It does not fit a team that only needs a one-off import, since the add-on and its dependencies are more than a file format reader. Before adopting it, confirm your Blender version is covered, since the install paths split at Blender 4.2, read the material tutorial because MToon has its own shader conventions, and note that the newest release is v4.10.2 from 2026-10-11 with the last push on 2026-10-12.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. saturday06/VRM-Addon-for-Blender on GitHub