rapidnbt 1.3.5

Python bindings for High-Performance NBT library

RapidNBT

Python Bindings for a High-Performance NBT Library

Install 🔧

pip install rapidnbt

Supported NBT format 📖

NBT Format	Minecraft Edition	Support Status
Little Endian	Bedrock Edition	:white_check_mark:
Little Endian with Header	Bedrock Edition	:white_check_mark:
Big Endian	Java Edition	:white_check_mark:
Big Endian with Header	Java Edition	:white_check_mark:
Bedrock Network (VarInt Encoding)	Bedrock Edition	:white_check_mark:
Formatted String (SNBT)	Bedrock & Java Edition	:white_check_mark:

Full SNBT support - Full SNBT format support, include the new SNBT format since Java Edition 1.21.5

Benchmarks 🚀

Comparing with some popular NBT libraries.

Parsing NBT file (870 MB, little-endian binary NBT)

Library	Link	Time	Performance	Memory Usage
RapidNBT	https://github.com/GlacieTeam/RapidNBT	5.2s	100%	4800MB
nbtlib	https://github.com/vberlier/nbtlib	33.9s	15.3%	6500MB
PyNBT	https://github.com/TkTech/PyNBT	33.4s	15.6%	8900MB

Tested on Intel i7 14700-HX with 32GB DDR5-5400 using 720MB little-endian binary NBT

Quick Start 🚀

RapidNBT provides a morden and safe API, and it is easy to use.

1. Load NBT from file and modify it

from rapidnbt import nbtio, LongTag
from ctypes import c_int16

def example():
    nbt = nbtio.load("./level.dat") # Automatically detect nbt file format and decompress (if compressed)
    # nbt = nbtio.load("./level.dat", NbtFileFormat.BIG_ENDIAN) # You can also specify the file format

    # Modify NBT
    nbt["abc"]["def"] = True # bool will automatically convert to ByteTag(1)
    nbt["ghi"]["hjk"] = c_int16(23) # ctypes.c_int16 will automatically convert to ShortTag(23)
    nbt["lmn"] = ["test1", "test2"] # Python list will automatically convert to ListTag([StringTag("test1"), StringTag("test2")])
    nbt["opq"]["rst"] = { # Python dict will automatically convert to CompoundTag
        "key1": False,
        "key2": b"2345",  # bytes/bytearray will automatically convert to ByteArrayTag
        "key3": LongTag(114514), # You can also directly use Tag
    }
    """
    You need not to create the NBT node first.
    Example:
        nbt["abc"]["def"] = True
        If nbt["abc"]["def"] does not exist, it will be auto created.
    """ 

2. Create a NBT in memory and save it to file

from rapidnbt import nbtio, CompoundTag, ShortTag, LongTag, DoubleTag, IntArrayTag, NbtFileFormat
from ctypes import c_uint8, c_double

# Create a NBT in memory
nbt = CompoundTag(
    {
        "string": "Test String",
        "byte": c_uint8(114),
        "short": ShortTag(19132),
        "int": 114514,
        "int64": LongTag(1145141919810),
        "float": 1.4142,
        "double": c_double(3.1415926535897),
        "byte_array": b"13276273923",
        "list": ["string1", "string2"],
        "compound": nbt,
        "int_array": IntArrayTag([1, 2, 3, 4, 5, 6, 7]),
        "long_array": LongArrayTag([1, 2, 3, 4, 5, 6, 7]),
    }
)

# Print SNBT
print(nbt.to_snbt()) 
# Or you can specify SNBT format
print(file.to_snbt(format=SnbtFormat.Classic | SnbtFormat.MarkExtra, indent=4))
# Use | to combime format 

# Save NBT to file
nbtio.dump(nbt, "./test.nbt", NbtFileFormat.LITTLE_ENDIAN)

3. Use context manager to operate NBT file

from rapidnbt import LongTag, nbtio

# use context manager
with nbtio.open("level.dat") as file:
    file["RandomSeed"] = LongTag(1145141919810) # modify NBT
    # Auto save file as original format when exit context manager

4. Read NBT data

from rapidnbt import nbtio

def example():
    nbt = nbtio.load("./test.nbt") # Automatically detect nbt file format and decompress (if compressed)
    
    value1 = nbt["abc"]["def"].value # Use .value method to get any tag value, and returns a Python object (Python int, str, dict, etc...)

    value2 = nbt["ghi"]["hjk"].get_short() # Use .get_xxx method to safely get tag value, and will throw TypeError if tag is wrong type

    exits = "lmn" in nbt # Check if a tag exist in this NBT
    # exits = nbt.contains("lmn") You can also use .contains() method to check

    del nbt["opq"]["rst"] # Delete a tag in NBT
    # nbt["opq"].remove("rst") You can also use .remove() method to delete
    
    nbt.rename("abc", "ABC") # Rename a key in NBT

More details please see the docstring in .pyi file

CLI 🔧

You can use CLI commands to opeartor NBT files easily.
Use nbt or python -m rapidnbt to run CLI

options:
  -h, --help            show this help message and exit
  -p, --print           print NBT as a formatted string
  -i, --indent INDENT   NBT format indent
  -j, --json            format NBT as a json string
  -o, --output OUTPUT   NBT output file path
  --little              NBT output should use little endian format
  --big                 NBT output should use big endian format
  --network             NBT output should use bedrock network format
  --snbt                NBT output should use a formatted string nbt
  --header              NBT output should write header
  -m, --merge           NBT output should merge exist NBT
  --merge-list          NBT should merge ListTag instead of replace it
  -c, --compression {none,gzip,zlib}
                        NBT output should merge exist NBT

1. Print a NBT file as SNBT
eg. level.dat

nbt level.dat -p

2. Print a NBT file as a json
eg. level.dat, indent = 2

nbt level.dat -pj --indent=2

3. Convert a NBT file to other format
eg. convert level.dat to SNBT and save as level.snbt

python -m rapidnbt level.dat --output=level.snbt --indent=0

4. Merge NBT
eg. use player1.nbt to patch player2.nbt (little-endian, no compression)

nbt player1.dat --output=player2.nbt --merge --little --compression=none

Used Libraries 📖

Library	License	Link
NBT	MPL-2.0	https://github.com/GlacieTeam/NBT
pybind11	BSD-3-Clause	https://github.com/pybind/pybind11
magic_enum	MIT	https://github.com/Neargye/magic_enum

Contributing 🤝

Contributions are welcome! Please follow these steps:

1. Fork the repository and create your feature branch
2. Add tests for any new functionality
3. Submit a pull request with detailed description

License 📄

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

Key Requirements:

• Modifications to this project's files must be released under MPL-2.0.
• Using this library in closed-source projects is allowed (no requirement to disclose your own code).
• Patent protection is explicitly granted to all users.

For the full license text, see LICENSE file or visit MPL 2.0 Official Page.

---

Copyright © 2025 GlacieTeam. All rights reserved.