Provide easy access to minecraft-data in Python.

This is a fork of the original python-minecraft-data with modern packaging infrastructure and lazy data loading using Pooch.

• Lazy data loading — Data is downloaded on-demand using Pooch and cached locally
• Efficient caching — Downloaded data is cached in ~/.cache/minecraft_data (configurable)
• Modern packaging — Built with Poetry and PEP 517/518 standards
• Comprehensive tests — 90%+ code coverage with pytest
• CI/CD ready — GitHub Actions workflow with coverage enforcement

Clone and install from source:

git clone https://github.com/newexo/python-minecraft-data
cd python-minecraft-data
poetry install

import minecraft_data

# Load a specific version
mc_data = minecraft_data("1.21.6")

# Access version info
print(mc_data.version)

# Access items, blocks, etc. (if available for that version)
if hasattr(mc_data, 'items'):
    print(mc_data.items)

Currently supported for detailed testing:

• 1.20.5
• 1.21.6

Other versions in the minecraft-data repository are accessible but may have incomplete data.

The PrismarineJS minecraft-data repository does not ship full gameplay data for every Minecraft version. Some patch releases are published as stubs — directories containing only version.json (and occasionally dataPaths.json) — because their game data is unchanged from the previous full-data release. The stub still exists so that version.json can carry the correct protocol version number, but items.json, blocks.json, recipes.json, etc. are absent.

For the 1.20 and 1.21 series, the versions that ship full data (item/block/recipe/language/etc. JSON files) are:

• 1.20 series: 1.20, 1.20.2, 1.20.3, 1.20.5
• 1.21 series: 1.21.1, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.8, 1.21.9, 1.21.11

Stub-only versions (e.g. 1.20.1, 1.20.4, 1.20.6, 1.21) are still accessible via get_data_path() but only expose version.json. If you need full gameplay data for one of those versions, use the nearest preceding full-data version from the list above.

This library provides Python access to the PrismarineJS minecraft-data project, which contains comprehensive Minecraft game data in JSON format.

Set the MINECRAFT_DATA_DIR environment variable to use a custom cache directory:

export MINECRAFT_DATA_DIR=/custom/path/to/minecraft/data
python your_script.py

make test

make check      # Format, lint, and test
make format     # Black formatting
make lint       # Flake8 linting

make coverage           # Terminal report
make coverage-html      # HTML report

MIT — See LICENSE for details.

• Original author: Vito Gamberini
• Game data source: PrismarineJS minecraft-data
• Maintained fork: Reuben Brasher