# PythonMC<\/p>\n
PythonMC is a server-side Fabric mod that adds lightweight Python scripting to Minecraft 1.21.1.<\/p>\n
It lets server owners write simple Python scripts for common automation, player messages, server events, and command-driven behavior without recompiling the mod.<\/p>\n
## Features<\/p>\n
– Loads Python scripts from the server config folder.
\n– Starts and manages a local Python 3.8+ script host automatically.
\n– Provides server lifecycle, tick, and player connection events.
\n– Exposes a small API for logging, broadcasting, private messages, and server command execution.
\n– Includes `\/pythonmc` admin commands for status, reloads, restarts, custom events, and quick Python snippets.
\n– Ships with an example script on first launch.<\/p>\n
## Requirements<\/p>\n
– Minecraft 1.21.1
\n– Fabric Loader 0.18.4 or newer
\n– Fabric API
\n– Java 21
\n– Python 3.8 or newer installed on the server<\/p>\n
Python must be available as `python3` or `python` on the server `PATH`.<\/p>\n
If Python is installed somewhere else, set one of these before launching Minecraft:<\/p>\n
“`text
\n-Dpythonmc.python=\/path\/to\/python
\n“`<\/p>\n
or:<\/p>\n
“`text
\nPYTHONMC_PYTHON=\/path\/to\/python
\n“`<\/p>\n
## Installation<\/p>\n
1. Install Fabric Loader for Minecraft 1.21.1.
\n2. Install Fabric API.
\n3. Put the PythonMC jar in the server `mods` folder.
\n4. Make sure Python 3.8+ is installed on the machine running the server.
\n5. Start the server once.<\/p>\n
PythonMC will create this folder:<\/p>\n
“`text
\nconfig\/pythonmc\/scripts
\n“`<\/p>\n
It will also create a starter script:<\/p>\n
“`text
\nconfig\/pythonmc\/scripts\/main.py
\n“`<\/p>\n
## Writing Scripts<\/p>\n
Scripts are normal `.py` files inside:<\/p>\n
“`text
\nconfig\/pythonmc\/scripts
\n“`<\/p>\n
Files whose names start with `_` are ignored. After editing scripts, reload them in-game or from the server console:<\/p>\n
“`text
\n\/pythonmc reload
\n“`<\/p>\n
Basic example:<\/p>\n
“`python
\nimport pythonmc_api as mc<\/p>\n
def on_server_started(ctx):
\n mc.log(“PythonMC script loaded.”)<\/p>\n
def on_player_join(ctx):
\n mc.tell(ctx[“name”], “Welcome! This message came from PythonMC.”)
\n“`<\/p>\n
## Script API<\/p>\n
Import the bundled API like this:<\/p>\n
“`python
\nimport pythonmc_api as mc
\n“`<\/p>\n
Available functions:<\/p>\n
“`python
\nmc.log(message, level=”info”)
\nmc.broadcast(message)
\nmc.tell(player_name, message)
\nmc.execute(command)
\n“`<\/p>\n
`mc.execute(command)` runs a Minecraft server command as the server command source. Use it carefully.<\/p>\n
## Events<\/p>\n
PythonMC calls functions in your scripts when matching events happen.<\/p>\n
Supported event handlers:<\/p>\n
“`python
\ndef on_server_started(ctx): …
\ndef on_server_stopping(ctx): …
\ndef on_server_tick(ctx): …
\ndef on_player_join(ctx): …
\ndef on_player_leave(ctx): …
\ndef on_shutdown(ctx): …
\ndef on_event(event_name, ctx): …
\n“`<\/p>\n
The `ctx` object contains event data. It supports both dictionary-style access and `.get()`:<\/p>\n
“`python
\ndef on_player_join(ctx):
\n player_name = ctx[“name”]
\n player_uuid = ctx.get(“uuid”)
\n“`<\/p>\n
Common player event fields:<\/p>\n
“`text
\nname
\nuuid
\n“`<\/p>\n
Common server event fields:<\/p>\n
“`text
\nplayers
\nmax_players
\ntick
\nscripts_dir
\n“`<\/p>\n
## Commands<\/p>\n
All commands require permission level 4.<\/p>\n
“`text Command details:<\/p>\n – `\/pythonmc status` shows whether the Python host is running and where scripts are loaded from. Custom event example:<\/p>\n “`python def on_event(event_name, ctx): Then run:<\/p>\n “`text ## Security Notes<\/p>\n PythonMC scripts run on the server machine with the permissions of the Minecraft server process.<\/p>\n Only install or write scripts you trust. A Python script can perform normal Python file and process operations, and `mc.execute()` can run Minecraft commands from the server command source.<\/p>\n For public or shared servers, restrict `\/pythonmc` command access to trusted operators only.<\/p>\n ## Server Side Only<\/p>\n PythonMC is intended for server-side scripting. Clients do not need to install the mod when connecting to a server that uses it, unless your modpack or server setup requires matching mod lists.<\/p>\n ## Troubleshooting<\/p>\n If scripts do not start:<\/p>\n – Run `\/pythonmc status`. If script changes do not apply:<\/p>\n – Make sure the file is in `config\/pythonmc\/scripts`. This mod adds python coding to fabric.<\/p>\n","protected":false},"featured_media":127209,"template":"","meta":{"_minecraft_slug":"pythonmcmod","_minecraft_project_id":"C3SYBh3U","_minecraft_author":"Antara89","_minecraft_license":"CC-BY-4.0","_minecraft_downloads":7,"_minecraft_follows":0,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"pythonmcmod.zip","_minecraft_size_bytes":435091,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T12:55:43.710772Z","_minecraft_date_created":"2026-05-08T00:35:16.276767Z","_minecraft_date_modified":"2026-05-06T14:14:47.590698Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/pythonmcmod","_minecraft_icon_attachment_id":127209,"_minecraft_imported_at":"2026-06-07T11:34:39+00:00","_minecraft_import_hash":"ad168b21c2f588728107797230d732f9","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,126,92],"mod_loader":[99],"minecraft_version":[37],"class_list":["post-127208","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-management","mod_category-utility","mod_loader-fabric","minecraft_version-1-21-1"],"yoast_head":"\n
\n\/pythonmc status
\n\/pythonmc start
\n\/pythonmc stop
\n\/pythonmc restart
\n\/pythonmc reload
\n\/pythonmc py
\n“`<\/p>\n
\n– `\/pythonmc start` starts the Python script host if it is stopped.
\n– `\/pythonmc stop` stops the Python script host.
\n– `\/pythonmc restart` restarts the Python script host.
\n– `\/pythonmc reload` reloads scripts from `config\/pythonmc\/scripts`.
\n– `\/pythonmc py
\n– `\/pythonmc event
\nimport pythonmc_api as mc<\/p>\n
\n if event_name == “maintenance”:
\n mc.broadcast(“Server maintenance is starting soon.”)
\n“`<\/p>\n
\n\/pythonmc event maintenance
\n“`<\/p>\n
\n– Confirm Python 3.8+ is installed.
\n– Confirm `python3` or `python` works from the same environment that launches the Minecraft server.
\n– Set `-Dpythonmc.python=\/path\/to\/python` if needed.
\n– Check the server log for messages tagged with `pythonmc` or `[python]`.<\/p>\n
\n– Make sure the filename ends in `.py`.
\n– Make sure the filename does not start with `_`.
\n– Run `\/pythonmc reload`.
\n– Check the server log for Python traceback output.<\/p>\n","protected":false},"excerpt":{"rendered":"