Installing mods on a Hytale server is short enough to fit in a tweet, but most new operators still get tripped up by three things: which file goes where, why the mod "doesn't load" (usually a version mismatch), and how to debug it without flailing. Here's the full workflow.

TL;DR

  1. Download the mod archive from a trusted source.
  2. Drop the file into /opt/hytale/Server/mods/.
  3. Restart the server. Watch the log.

That's the happy path. The interesting bits are everything around it.

Where to get mods

Stick to official-ish distribution channels. The main ones for Hytale:

  • CurseForge — the biggest catalogue for Hytale mods, same platform that already hosts Minecraft/Terraria/etc. mods. Downloads have basic malware scanning.
  • Modrinth — open-source-friendly alternative; as Hytale's modding ecosystem matures, expect more mods to mirror here.
  • Author's GitHub — fine if you trust the author and can read the code.

Avoid: random Discord attachments, pirate-flavoured mod sites, anything packed as an .exe. Hytale mods are JVM code; they ship as .jar or .zip. If a "mod" is an executable, it's malware.

.jar vs .zip

Both are valid mod packages. A .jar is a single compiled plugin. A .zip is usually a multi-file mod (resources + compiled code + sometimes a manifest) shipped as an archive.

Good news: you drop both the same way. Hytale's server loader handles both. Do not extract the .zip — leave it as an archive.

Install a mod (Linux)

All operations run as the hytale user (see the main install guide for the user setup).

cd /opt/hytale/Server/mods/

# grab the mod (replace with the real URL)
sudo -u hytale wget https://example.com/some-cool-mod-1.2.0.jar

# list to sanity-check
ls -l

Permissions should already be correct if you wget'd as the hytale user. If you copied a file in as root by accident:

sudo chown hytale:hytale /opt/hytale/Server/mods/*

Restart the server:

sudo systemctl restart hytale
journalctl -u hytale -f

Watch the log for lines mentioning the mod's name or for errors. A successful load usually looks like Loaded plugin some-cool-mod v1.2.0 or similar; a failure is usually very loud with a stack trace.

Install a mod (Windows)

Drop the file into the mods folder inside your server install:

C:\HytaleServer\Server\mods\

Right-click the file → Properties → if there's an "Unblock" checkbox at the bottom, tick it. Windows likes to quarantine downloaded .jar/.zip files and the server will silently skip blocked ones on some setups.

Then restart the service (NSSM, Task Scheduler or however you're running it) and tail the log.

Load order & dependencies

Most mods load in a deterministic order the server decides based on declared dependencies. You almost never need to manually reorder anything.

What you do need to care about:

  • Required dependencies. If mod A says it depends on mod B, you need B in mods/ too. The log will tell you which is missing.
  • Version compatibility. A mod built for Hytale 2026.01.x may or may not work on 2026.02.x. If in doubt, read the mod's page — good authors list supported game versions.
  • API level. Hytale's modding API is young and will change. Expect to re-check mods after every major server update for the first year.

Early / experimental plugins

Some mods ship as "early plugins" — they load earlier than the normal plugin lifecycle to hook into things the public API doesn't expose yet. The server refuses to load them by default because they can destabilise everything.

If you know what you're doing, opt in with the flag:

./start.sh --accept-early-plugins

Or the equivalent in your systemd unit's ExecStart. Do not use this on a production community server. It's a "breaks on update, you keep both halves" switch.

Disable Sentry during mod development

The official Hytale server phones home crash reports via Sentry. If you're actively developing a mod, your half-broken code will spam their telemetry with noise that isn't theirs to look at. Turn it off:

./start.sh --disable-sentry

Only while you're developing. Re-enable for production — crash telemetry helps Hypixel Studios actually fix bugs.

Remove or update a mod

Remove:

sudo systemctl stop hytale
rm /opt/hytale/Server/mods/some-cool-mod-1.2.0.jar
sudo systemctl start hytale

Update: delete the old file first, then drop the new one. Leaving two versions side-by-side (mod-1.2.0.jar and mod-1.3.0.jar) is a classic way to hit weird conflicts where the old one still gets loaded.

Some mods persist data inside universe/. Removing the mod is not the same as removing its data — if the mod wrote custom blocks or entities into your world, those will turn into "unknown" placeholders. Back up universe/ before uninstalling any mod that has touched world state.

Troubleshooting — the five things that go wrong

  1. Wrong folder. Double-check the mod is inside Server/mods/, not next to start.sh or elsewhere. The wrapper changes directory into Server/ before launching.
  2. Version mismatch. Check the Hytale server version (/update status in the console) against the mod's declared compatibility.
  3. Missing dependency. The startup log will flag it explicitly: "Failed to load X: requires Y". Download Y.
  4. File corrupted on download. Size mismatch or zero bytes. ls -l and compare to the mod page's listed file size. Re-download.
  5. Permissions. If the server runs as hytale but the file is owned by root and mode 600, the server can't read it. chown hytale:hytale fixes it.

When you file a bug report to a mod author, include the relevant journalctl snippet. "It doesn't work" gets a shrug; a stack trace gets a fix.

Client vs server mods

Some Hytale mods are server-only (gameplay changes, admin tooling, performance tweaks). Others need the same mod on every connecting client (new blocks, entities, UI). The mod's documentation will say which.

If you're running a server for friends, a server-only mod is a free upgrade. If it's a content mod that requires client installation, plan the rollout: give players a pack to download, or host a simple "required mods" page on your Discord.

Keeping a clean mod list

Two habits that save pain later:

  • Keep a plain-text mods.md in /opt/hytale/ listing every mod, its version, and where you got it. When you wipe and rebuild (you will eventually), you'll thank yourself.
  • Update one mod at a time. If something breaks, you know which one.

Reference

Last updated: April 2026.