How to Add Mods to Your Hytale Docker Server (2026 Guide)

Adding mods to a Dockerized Hytale server is straightforward using Docker volumes and the docker cp command. Mods are stored in persistent volumes, ensuring they survive container restarts and updates while maintaining clean separation from the container image.

What you'll learn: Using docker cp to add mods, managing persistent mod storage with Docker volumes, updating mods without losing data, and troubleshooting Docker-specific mod issues.

Docker Setup Guide General Mod Installation Guide

Prerequisites

▸A running Hytale Docker server (see our Docker setup guide)
▸Docker installed and running on your system
▸Basic familiarity with Docker commands
▸Downloaded mod files (.jar or .zip)

Note: If you haven't set up your Docker server yet, follow our Docker setup guide first.

Understanding Docker Volumes & Mod Storage

How Mods Are Stored

When you run the Hytale Docker server using the recommended docker-compose.yml, your server data is stored in a Docker volume named hytale-data:

volumes:
- hytale-data:/hytale/Server

This volume persists all server data including mods, worlds, configs, and logs—even when you update or recreate the container.

Mods Directory Location

Inside the container, mods are stored at:

/hytale/Server/mods/

This path is mounted to the Docker volume, making it persistent across container restarts.

Method 1: Using docker cp (Recommended)

The docker cp command copies files directly into your running container's persistent volume.

Step 1: Download Your Mod

Download the mod file to your local machine. For example:

~/Downloads/awesome-mod-v1.2.jar

Step 2: Copy Mod to Container

Use docker cp to copy the mod into the container:

# General syntax
docker cp /path/to/mod.jar hytale-server:/hytale/Server/mods/

# Example on Linux/macOS
docker cp ~/Downloads/awesome-mod-v1.2.jar hytale-server:/hytale/Server/mods/

# Example on Windows
docker cp C:\Users\YourName\Downloads\awesome-mod-v1.2.jar hytale-server:/hytale/Server/mods/

Replace hytale-server with your container name if different.

Step 3: Verify the Mod Was Copied

# List files in mods directory
docker exec hytale-server ls -la /hytale/Server/mods

You should see your mod file listed.

Step 4: Restart the Server

docker compose restart

Check the logs to confirm the mod loaded:

docker compose logs -f

Method 2: Using Bind Mounts (Advanced)

For easier mod management, you can mount a local directory to the container's mods folder. This allows direct file access from your host system.

Modify docker-compose.yml

Update your docker-compose.yml to include a bind mount:

services:
hytale-server:
image: p0lgs/hytale-server-docker:latest
container_name: hytale-server
restart: unless-stopped

ports:
- "5520:5520/udp"

volumes:
- hytale-data:/hytale/Server
- ./mods:/hytale/Server/mods # Add this line

volumes:
hytale-data:

Create Mods Directory

# In your server directory
mkdir mods

Recreate Container

docker compose down
docker compose up -d

Add Mods Directly

Now you can add mods by simply copying them to your local mods/ folder:

# Linux/macOS
cp ~/Downloads/mod.jar ./mods/

# Windows
copy C:\Downloads\mod.jar .\mods\

Restart the container to load new mods.

Installing Multiple Mods at Once

Copy Multiple Files with docker cp

# Copy entire directory
docker cp ./local-mods-folder/. hytale-server:/hytale/Server/mods/

# Or copy multiple files individually
docker cp mod1.jar hytale-server:/hytale/Server/mods/
docker cp mod2.jar hytale-server:/hytale/Server/mods/
docker cp mod3.jar hytale-server:/hytale/Server/mods/

Restart once after copying all mods to load them together.

Managing Mod Configurations

Accessing Config Files

Mod configuration files are typically stored in /hytale/Server/config:

# View config files
docker exec hytale-server ls -la /hytale/Server/config

# View a specific config
docker exec hytale-server cat /hytale/Server/config/mod-config.json

Editing Config Files

Option 1: Copy, Edit, Copy Back

# Copy config from container
docker cp hytale-server:/hytale/Server/config/mod-config.json ./mod-config.json

# Edit with your preferred editor
nano mod-config.json

# Copy back to container
docker cp ./mod-config.json hytale-server:/hytale/Server/config/mod-config.json

# Restart to apply
docker compose restart

Option 2: Edit Directly in Container

docker exec -it hytale-server sh
cd /hytale/Server/config
vi mod-config.json # or nano, if available
exit

Updating Mods

Replace Old Mod Version

1.
Remove the old version:
docker exec hytale-server rm /hytale/Server/mods/old-mod-v1.0.jar
2.
Copy the new version:
docker cp new-mod-v1.1.jar hytale-server:/hytale/Server/mods/
3.
Restart the container:
docker compose restart

Removing Mods

Delete Mod File

# Remove specific mod
docker exec hytale-server rm /hytale/Server/mods/unwanted-mod.jar

# Restart to unload the mod
docker compose restart

Some mods may leave config files behind. Check /hytale/Server/config and remove mod-specific configs if desired.

Troubleshooting Docker Mod Issues

Mod Not Loading

Checklist:

▸Verify the file was copied correctly: docker exec hytale-server ls /hytale/Server/mods
▸Check container logs for errors: docker compose logs -f
▸Ensure you restarted the container after adding the mod
▸Check file permissions inside the container

Permission Denied Errors

If you get permission errors when copying files:

# Fix permissions inside container
docker exec hytale-server chmod 644 /hytale/Server/mods/*.jar

Mods Disappear After Container Update

If mods disappear when you update the container image, ensure you're using a named Docker volume (e.g., hytale-data) and not an anonymous volume. Check your docker-compose.yml has the volumes section properly configured.

Cannot Find Container

If docker cp fails with "no such container":

# List running containers
docker ps

# Use the actual container name from the output

The default name is hytale-server but may differ based on your configuration.

Best Practices for Docker Mod Management

1. Always Use Named Volumes

Named volumes ensure your mod data persists across container updates and recreations. Avoid anonymous volumes or you risk losing data.

2. Back Up Your Volume

Regularly back up your Docker volume containing mods and server data:

docker run --rm --volumes-from hytale-server -v $(pwd):/backup ubuntu \
tar czf /backup/hytale-backup.tar.gz -C /hytale/Server .

3. Document Your Mods

Keep a list of installed mods and their versions in a README or text file. This makes it easier to reproduce your setup or troubleshoot issues.

4. Test Mods Before Production

Always test new mods on a development server before adding them to your production environment. Use a separate docker-compose configuration for testing.

Your Dockerized Server is Enhanced!

You've successfully learned how to manage mods in your Dockerized Hytale server using docker cp and persistent volumes. Your mods will survive container updates and restarts, giving you a production-ready, customizable server environment.

List Your Server Port Forwarding Guide →

Related Guides