Python MOD

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

| Function | Registers |
| — | — |
| block(id, hardness, resistance, requires_tool, luminance, sounds, group, item, texture, name) | A full-cube block, optionally with a block item |
| item(id, max_stack, group, texture, name) | A plain item |
| food(id, nutrition, saturation, always_edible, max_stack, group, texture, name) | An edible item |

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

| Event | Arguments |
| — | — |
| server_tick | (server) |
| server_started / server_stopping | (server) |
| player_join / player_leave | (player) |
| block_break | (player, pos, block) |
| block_use | (player, pos) |
| item_use | (player) |
| client_tick | (client) |

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>

| Attribute | On | Meaning |
| — | — | — |
| style / style_dark | widget | CSS-like key:value pairs (color, bg, border). The active light/dark theme picks which one |
| click_script | button, checkbox | Python file run when the widget is clicked |
| follow_script | button | Python file run right after click_script completes |
| show_page | screen | Where to show it: hud (in-game overlay). screen / main_menu are reserved |
| x / y | screen, widget | Coordinates in GUI pixels; the screen is the panel anchor, a widget is relative to it |

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

| Field | Required | Notes |
| — | — | — |
| id | yes | 2–64 chars of a-z, 0-9, _. Becomes your registry namespace |
| version | yes | Free-form |
| api_version | yes | Must be 1. See Attribution below |
| name | no | Defaults to id |
| description | no | Shown in the manager screen |
| authors | no | Array of strings |
| entrypoint | no | Defaults to src/main.py |
| environment | no | *, client or server |
| permissions | no | See the table below |

Permissions

| Permission | Risk | Grants |
| — | — | — |
| file_read | low | Reading inside your own data folder |
| file_write | medium | Writing inside your own data folder |
| network | high | Outbound sockets |
| thread | high | Creating threads |
| native | critical | Native/JNI access — effectively no sandbox |
| process | critical | Spawning processes — effectively no sandbox |

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

| Key | Default | Meaning |
| — | — | — |
| enabled | true | Master switch |
| autoDownloadRuntime | true | Fetch GraalPy on first launch |
| mavenRepository | Maven Central | Mirror to download from |
| verifyChecksums | true | Verify every downloaded jar |
| theme | "auto" | auto, light or dark |
| callbackTimeoutMs | 5000 | A callback exceeding this disables its package |
| verboseLogging | false | Extra diagnostics |

---

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.