UnityPy

1.25.0 verified Fri May 01 auth: no python

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.

pip install unitypy

Common errors

error ModuleNotFoundError: No module named 'UnityPy' ↓

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

fix

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

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

cause 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'.

error KeyError: 'Texture2D' ↓

cause 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)

error lz4.error.LZ4F_error_decompression ↓

cause 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.

error cryptodome.CryptoError: Wrong key ↓

cause 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.

Warnings

gotcha The 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.

gotcha When 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.

breaking In 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'.

gotcha Reading 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.

deprecated The 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.

Imports

AssetsManager

wrong

from UnityPy.environment import AssetsManager

correct

from UnityPy import AssetsManager

AssetsManager is at top level since v1.5.0

File

wrong

from UnityPy.files import File

correct

from UnityPy import File

File class is at top level since v1.15.0

Environment

wrong

from UnityPy.environment import Environment

correct

from UnityPy import Environment

Environment is at top level since v1.0.0

Quickstart

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