Python MOD

Write Minecraft mods in Python.

Python MOD is a Fabric mod that embeds a real Python 3 runtime into Minecraft and exposes a sandboxed API for registering content, hooking game events and building screens. Drop a .pymod file into a folder, restart, and your Python is running inside the game — no Java, no Gradle, no recompiling.

• Minecraft 1.21.1 · Fabric Loader 0.16+ · Fabric API
• Runtime: GraalPy 24.2.2 (CPython 3.11 compatible)
• API level: 1
• Licence: Available License — © 2026 kscm · Project Owner: kscm

Hello, world

hello_world.pymod is a zip with two files:

hello_world.pymod
├── pymod.json
└── src/
    └── main.py

pymod.json

{
  "id": "hello_world",
  "name": "Hello World",
  "version": "1.0.0",
  "api_version": 1,
  "entrypoint": "src/main.py",
  "permissions": []
}

src/main.py

import pythonmod
from pythonmod import registry, events

registry.block("hello_block", hardness=1.0, sounds="wood", name="Hello Block")

@events.player_join
def greet(player):
    player.send_message("Hello from Python!")

Put it in .minecraft/mods/pythonmods/, start the game, press P.

What the API covers

pythonmod.registry — content

Everything is namespaced under your module id, so block("ruby_ore") in a package with "id": "gems" becomes gems:ruby_ore. Two unrelated packages can both define ruby_ore and never collide.

Models and English names are generated into a PythonMOD Generated resource pack, so new content is usable before you have drawn a single texture.

pythonmod.events — game hooks

from pythonmod import events

@events.block_break
def on_break(player, pos, block):
    player.send_actionbar("broke %s at %d,%d,%d" % (block.id(), pos.x(), pos.y(), pos.z()))

An unrecognised event name raises at subscription time. A hook that silently never fires is the most expensive kind of typo, so it is not allowed to happen.

pythonmod.gui — screens

from pythonmod import gui

(gui.screen("Ore Scanner")
    .size(280, 160)
    .label("Radius", 20, 34)
    .slider("blocks", 20, 48, 240, value=16, min=4, max=64, on_change=set_radius)
    .checkbox("Include deepslate", 20, 80, checked=True, on_change=set_deepslate)
    .button("Scan", 20, 110, 240, 20, on_click=scan)
    .open())

Coordinates are relative to the panel and the panel is centred for you. Light and dark palettes are built in and follow the player's setting — a script never picks colours by hand.

On a dedicated server there is no client, so open() returns False and logs a warning instead of raising. Guard with gui.available() when a package is meant to run on both sides.

pythonmod.xmlgui — declarative HUD (XML)

Declare an in-game HUD panel in gui/*.xml — no Python screen code required. Each module's gui/ folder is scanned automatically at load time.

gui/hud.xml

<gui>
  <screen id="hud_demo" show_page="hud" x="12" y="12">
    <label id="title" text="Python MOD · XML HUD" x="0" y="0"
           style="color:#1b1f24" style_dark="color:#eceff3"/>
    <divider x="0" y="20" w="180"/>
    <button id="mine" text="Mine +1" x="0" y="30" w="160" h="20"
            style="bg:#1565c0;color:#ffffff" style_dark="bg:#5fa8ff;color:#0b0e12"
            click_script="on_click.py" follow_script="after.py"/>
    <checkbox id="auto" text="Auto mine" x="0" y="58" checked="true"
              style="color:#1b1f24" style_dark="color:#eceff3"
              click_script="on_toggle.py"/>
    <slider id="speed" text="Speed" x="0" y="84" w="180" value="0.5" min="0" max="1"/>
    <text_field id="status" placeholder="Status: ready" x="0" y="110" w="180" h="20"/>
  </screen>
</gui>

The scripts run in an isolated context — same permissions and sandbox as the module, but a crash disables only that script, never the whole module. They can import pythonmod like any other code. A clicked button runs click_script then follow_script; the same path is reachable from Python:

from pythonmod import xmlgui
xmlgui.trigger("hud_demo", "mine")   # runs on_click.py then after.py

See examples/xml_hud_demo/ for a complete, runnable panel (button, checkbox, slider and text field with light/dark styles and Python scripts).

The manifest

Permissions

The sandbox confines file access to pythonmod/data/<your-id>/ regardless of what is granted. pythonmod.data_path("state.json") builds a legal path; anything outside that tree is refused before it reaches the filesystem.

Packages asking for native or process produce a loud warning in the log and a red entry in the manager screen. That is deliberate: those two permissions hand a script the same power a Java mod has.

In-game manager

Press P (rebindable) for:

• what loaded, what failed, and the exact reason
• what each package registered, and how long it took
• the permissions it was granted, colour-coded by risk
• the last few lines it printed
• a light / dark / auto theme switch, saved to the config

Configuration

.minecraft/config/pythonmod.json

How it works

preLaunch   RuntimeProvisioner   downloads GraalPy, verifies SHA-1,
                                 injects it into the Knot class loader
   ↓
main        PythonEngine         one shared Engine
            SandboxPolicy        one Context per package, with its own
                                 permission set and virtual filesystem
            PyModLoader          scan → validate → unpack → run
            PyBridge             the single Java object Python can reach
   ↓
runtime     PyEventBridge        Fabric callbacks fan out to Python hooks
            PyGuiBridge          screen descriptions, rendered client-side
            XmlHudRenderer       XML-declared HUD panels, scanned from gui/*.xml
            XmlGuiBridge         fires a widget's click/follow scripts

The runtime is not bundled. GraalPy is roughly 200 MB — larger than most modpacks. It is downloaded once on first launch, checksum-verified, and cached in .minecraft/pythonmod/runtime/. If the download fails the game still starts; Python support is simply reported as unavailable.

One context per package, not one shared context. A polyglot context cannot hold two different permission sets, so a shared one would grant every package the union of everyone's permissions — one package asking for network would silently hand network access to all the others. Separate contexts also mean a crashing package can be disabled on its own.

Guest exceptions never escape. Every call into Python goes through PythonEngine.invoke, which catches the guest exception, prints the Python traceback, and disables the offending package. A typo in a script is not allowed to take the server down.

Building

Requires JDK 21. A local Temurin 21 lives in .tooling/jdk-21; point org.gradle.java.home in gradle.properties at your own if you prefer.

./gradlew build          # builds the mod jar
./gradlew packExamples   # packs examples/ into build/pymods/*.pymod

Attribution

Python MOD is distributed under the Available License (see LICENSE), © 2026 kscm, Project Owner kscm.

Section 6 requires software using this API to state the original project name and version. Python MOD does that for you:

• api_version is mandatory in every manifest — a package without it is refused rather than silently loaded
• the loader prints <package> v<version> — Powered by Python MOD v<x.y.z> (API <n>) when the package starts
• the same string is available as pythonmod.ATTRIBUTION
• gradlew packExamples writes ATTRIBUTION.txt into every archive

Declaring api_version is therefore all an author has to do.

Section 3 — using this project's source code requires authorisation from the Project Owner, and any such use must state the original project name, team and version.

Section 7 — "Python MOD" is used as the sole project name; no translated name is claimed or authorised.

Not affiliated with Mojang Studios or Microsoft.