unitypy

library1.25.0pypypi✓ verified 85d ago

A Python library for extracting and patching Unity assets (AssetBundle, SerializedFile, etc.). It supports reading and modifying Unity assets from Unity 4.x to 2022.x. Current version 1.25.0, requires Python >=3.8, MIT license. Active development, frequent releases.

serialization devops

pip install unitypy

github ↗package ↗

INSTALL

IMPORT

SIG · UNITYPY

unitypy

serializationpythonv1.25.0

Install

3.6s avg

Import

3506ms

Disk

86MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.25.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.6s · import 3.506s · 88MB

86MB installed

● package 86MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AssetsManager

✓ from UnityPy import AssetsManager

✗ from UnityPy.environment import AssetsManager

AssetsManager is at top level since v1.5.0

File

✓ from UnityPy import File

✗ from UnityPy.files import File

File class is at top level since v1.15.0

Environment

✓ from UnityPy import Environment

✗ from UnityPy.environment import Environment

Environment is at top level since v1.0.0

Load an asset bundle, read all objects, and export first Texture2D as PNG.

from UnityPy import AssetsManager import os env = AssetsManager() # Load a Unity asset bundle file env.load_file('example.bundle') for asset in env.assets: for obj in asset.objects: # Check object type if obj.type.name == 'Texture2D': data = obj.read() # Save as PNG data.image.save('output.png', 'PNG') break

Debug

Known issues

gotchaThe AssetsManager must be created before loading files. Loading files directly with File class without an environment may cause missing dependencies or incomplete asset graph.

fix

Always instantiate AssetsManager (or Environment) and use its load_file method.

affects: >=1.0

gotchaWhen modifying assets, you must call obj.save() on each changed object and then environment.pack() to rebuild the bundle. Failure to do so results in lost changes.

fix

After setting properties, call obj.save() and then env.pack() before writing the output file.

affects: >=1.0

breakingIn version 1.15.0, the File class was moved from UnityPy.files to UnityPy directly. Old imports will break.

fix

Use 'from UnityPy import File' instead of 'from UnityPy.files import File'.

affects: <1.15.0

gotchaReading object properties requires calling obj.read() before accessing data. Otherwise, you get empty or None values.

fix

Always call obj.read() to deserialize the object data.

affects: >=1.0

deprecatedThe Environment class is deprecated in favor of AssetsManager since version 1.20.0. It may be removed in the future.

fix

Use AssetsManager instead of Environment.

affects: >=1.20.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'UnityPy'

UnityPy is not installed or is installed in a different environment.

fix

Run 'pip install unitypy' in your active Python environment.

AttributeError: module 'UnityPy' has no attribute 'AssetsManager'

Old import path used or outdated version (<1.5.0).

fix

Ensure you have at least version 1.5.0: 'pip install unitypy>=1.5.0' and use 'from UnityPy import AssetsManager'.

KeyError: 'Texture2D'

Trying to access a type name that doesn't exist in the loaded bundle.

fix

Check the type via obj.type.name or iterate over all objects to find the correct type. Use a loop: for obj in asset.objects: print(obj.type.name)

lz4.error.LZ4F_error_decompression

Corrupt or unsupported compression settings in the asset bundle.

fix

Verify the bundle is valid. Try using lz4 version 4.0.2+. If the bundle uses block compression, upgrade UnityPy and lz4.

cryptodome.CryptoError: Wrong key

Encryption key mismatch for decryption.

fix

Provide the correct encryption key via AssetsManager(key=your_key). If not set, the library may try default keys.

Upgrade

Version history

1.25.0latest on PyPI · released Feb 23, 2026

Audit

Dependencies

lz4requiredDecompression of Unity LZ4 blocks

PillowrequiredTexture decoding and encoding (PNG, JPEG, etc.)

pycryptodomeoptionalAES decryption for encrypted bundles

typeguardrequiredRuntime type checking used internally

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/K0lb3/UnityPy ↗

packagehttps://pypi.org/project/unitypy/ ↗