nbtlib

What it is and what it does

nbtlib is a Python library for reading, writing, and editing NBT (Named Binary Tag) files, the binary format Minecraft uses to store structured data. It provides both a programmatic API and a command-line tool for working with NBT data. The library treats NBT tags as Python objects that inherit from their built-in counterparts (e.g., NBT Compound tags inherit from dict, Int tags from int), making it natural to read and manipulate NBT data using standard Python operations.

The package supports multiple NBT variants: gzipped and uncompressed files, big-endian and little-endian byte orders, and both binary and literal (text) notation. It includes schema support for enforcing specific tag types on compound structures, NBT path syntax for accessing deeply nested properties, and a CLI for quick read/write/merge operations on NBT files. A single runtime dependency (numpy) keeps installation straightforward.

Use it for:

• Parse and inspect Minecraft world data, player data, or schematic files stored in NBT format
• Programmatically modify NBT structures (player inventories, world properties, entity data) for server administration or data migration
• Convert NBT data between binary and human-readable literal notation for debugging or documentation
• Define and validate NBT schemas to ensure data integrity when working with structured Minecraft data
• Build tools or utilities that read or generate NBT files for Minecraft mods, datapacks, or server plugins

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Read, write, and edit NBT (Named Binary Tag) data files used in Minecraft, with support for gzipped and uncompressed formats, big-endian and little-endian byte orders, and schema validation.

Yes, with conditions. nbtlib is the standard library for NBT handling in Python and has no known vulnerabilities. However, the project is abandoned (last commit December 2022, last release November 2021) and version 2.0.4 is explicitly marked unstable—use the stable 1.12.1 release for production work. If you need to work with NBT files and can tolerate no further upstream updates, it remains reliable; if you need active maintenance or expect format changes, verify that 1.12.1 meets your needs before committing.

Install

nbtlib on PyPI

pip install nbtlib

uv add nbtlib

poetry add nbtlib

Installing nbtlib

Before you install

Low install friction with a single runtime dependency (numpy). However, the package is in abandoned maintenance status with the last commit in December 2022 and no releases since November 2021. The current stable version is 1.12.1; version 2.0.4 is explicitly marked as unstable and actively worked on.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute nbtlib freely in commercial and private projects without restriction.

Quickstart

import nbtlib
from nbtlib.tag import Int

# Load and read
nbt_file = nbtlib.load('demo.nbt')
value = nbt_file['counter']

# Edit and save
with nbtlib.load('demo.nbt') as demo:
    demo['counter'] = Int(demo['counter'] + 1)

Requires Python 3.8 or later. Version 2.0.4 is unstable; the description recommends using version 1.12.1 for production use.

Verify before relying

• Whether version 2.0.4 is suitable for production use or if 1.12.1 should be preferred despite being older
• Current compatibility with modern Minecraft NBT format versions
• Whether the abandoned maintenance status affects real-world reliability for typical use cases

Package facts

Evidence: nbtlib-2.0.4-py3-none-any.whl

Keywords: nbt, nbt-parser, schema, minecraft, nbtlib

Tags

More Utilities packages