Skip to main content

A python library for reading and writing NBT files

Project description


A python library for reading and writing NBT files. Compatible with json.

Based on NBT Version: 19133 (Current version used by Minecraft)

What is NBT

NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.

From official Minecraft Wiki.


pip install Python-NBT


Read an NBT file

>>> import python_nbt.nbt as nbt
>>> file = nbt.read_from_nbt_file("file.nbt")

This function returns an instance of NBTTagCompound, or by the name on Minecraft Wiki, an instance of TAG_Compound. It only accept 1 argument, which can be either a file path string or an opened file stream.

The TAG_Compound acts like a dict in Python. More accurately, it is a subclass of dict in Python with some restrictions put on its keys and values. So you can get, and set its items as shown below:

>>> file['drop_loot_crates']
{'type_id': 1, 'value': 0}
>>> file['drop_loot_crates'] = nbt.TAG_Byte(1)
>>> file['drop_loot_crates']
{'type_id': 1, 'value': 1}

In the dict shown as above, the key 'type_id' represents the type id of an NBT. In our example, its 'type_id' is 1, which indicates this NBT is a TAG_Byte. And 'value' indicates its actual value.

Write an NBT file

Once you've completed editing an NBT, you can store it into an NBT file with the function below:

write_to_nbt_file(file, tag)

The first argument file should be a path string or a file stream to the file you want to create/write. The second argument tag is the NBT you want to write.

Compat with Json

If you want to export NBT in json, you can use NBTTagBase.json_obj(full_json=True) to get an json style dict that contains all the NBT information. After that, you can use json module in Python to do whatever you want. If you want a simpler version, which omits type id of an NBT and NBTs inside it, set full_json to False. Note: Changing full_json to False will also turn json dict of nested tags into simple version.

If you want to import NBT from a json object, you can use nbt.from_json(json_obj) to do so. This function will return an NBT object. And its argument must be as same format as what NBTTagBase.json_obj(full_json=True) exports.

Future features

Ticked entries are finished.

  • [x] More json compat
    • [x] Convert json into NBT
    • [x] Better and configurable json output (omitting NBT types)
  • [ ] Convenient classes for reading and writing Minecraft saves files
    • [ ] World
    • [ ] Region
    • [ ] Chunk
    • [ ] ItemStack
    • [ ] TileEntity
    • [ ] Entity
    • [ ] Player
  • [ ] Utilities for mods
  • [x] A detailed ~~doc/~~wiki
  • [ ] More convenient interfaces for NBT (try to fully abandon value property, and makes everthing just it should be)
    • [ ] Operators for numeric tags
      • [ ] +, -, *, /
      • [ ] **, //
      • [ ] >, <
    • [x] List interfaces for array-like NBT
    • [x] Dict interfaces for dict-like NBT

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Python-NBT, version 1.2.0
Filename, size File type Python version Upload date Hashes
Filename, size Python_NBT-1.2.0-py3-none-any.whl (21.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size Python-NBT-1.2.0.tar.gz (8.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page