Skip to main content
Modrinth is an open source modding platform with a clean, easy to use website for finding mods, plugins, and datapacks. At startup, the container automatically locates and downloads the newest versions of files that correspond to your server’s TYPE and VERSION. Older file versions are automatically cleaned up.

​
Basic Usage

Set MODRINTH_PROJECTS to a comma or newline separated list of projects. 
environment:
  TYPE: FABRIC
  VERSION: "1.21.4"
  MODRINTH_PROJECTS: |
    fabric-api
    lithium
    ferritecore

​
Project Entry Formats

Each project entry can use one of these formats (where : separates parts): 
         Project
         Project : Version
         Project : Release Type
Prefix : Project
Prefix : Project : Version
Prefix : Project : Release Type
@ Listing File

​
Components

Project - The project slug or ID
  • Slug: The part of the URL after /mod/, /plugin/, or /datapack/
  • ID: Copy from the project page menu
Version - Version ID (like “Oa9ZDzZq”) or number (like “2.21.2”)
  • When omitted, the latest release version is selected
  • Using version ID overrides Minecraft and loader compatibility checks
  • Find on version-specific pages like https://modrinth.com/plugin/essentialsx/version/2.21.2
Release Type - release, beta, or alpha
  • Selects the latest version of that type
Prefix - datapack, fabric, forge, or paper
  • datapack is optional when running a vanilla server
  • fabric, forge, and paper allow installing mods/plugins that differ from server’s TYPE
  • Example: Use fabric: prefix to load Fabric mods into a NeoForge server via Sinytra Connector
Listing File - Container path to a file containing project list
  • Must start with @

​
Examples

DescriptionExample
Select latest versionfabric-api
Select specific version by IDfabric-api:bQZpGIz0
Select specific version by numberfabric-api:0.119.2+1.21.4
Select latest beta versionfabric-api:beta
Latest version using project IDP7dR8mSH
Latest version of datapackdatapack:terralith
Specific version of datapackdatapack:terralith:2.5.5
Mod loader overridefabric:fabric-api
Fabric mod with specific versionfabric:fabric-api:bQZpGIz0
Projects listing file@/path/to/modrinth-mods.txt

​
Using Listing Files

Create a text file with one project per line. Blank lines and comments (starting with #) are ignored.
1

Create a listing file

Create modrinth-mods.txt:
# Performance mods
fabric-api
lithium
ferritecore

# Utility mods
cloth-config

# Datapacks
datapack:terralith
2

Mount the file in your container

volumes:
  - ./modrinth-mods.txt:/extras/modrinth-mods.txt:ro
3

Reference it in MODRINTH_PROJECTS

environment:
  MODRINTH_PROJECTS: "@/extras/modrinth-mods.txt"

​
Auto-Removal

Entries removed from MODRINTH_PROJECTS will be automatically removed from the mods or plugins directory.
An empty MODRINTH_PROJECTS list will remove all previously installed mods/plugins.To temporarily disable processing without removing files, comment out the MODRINTH_PROJECTS environment variable entirely.

​
Version from Projects

Automatically determine the Minecraft VERSION based on your projects by setting VERSION_FROM_MODRINTH_PROJECTS=true. The container will select the most recent Minecraft version supported by all listed projects. Example: 
environment:
  MODRINTH_PROJECTS: |
    viaversion
    viabackwards
    griefprevention
    discordsrv
  VERSION_FROM_MODRINTH_PROJECTS: "true"
If all plugins support Minecraft 1.21.8 except griefprevention (only supports up to 1.21.7), then VERSION will automatically be set to 1.21.7.

​
Dependencies

Control whether project dependencies are automatically downloaded: 
MODRINTH_DOWNLOAD_DEPENDENCIES: required
ValueDescription
noneDon’t download dependencies (default)
requiredDownload required dependencies only
optionalDownload both required and optional dependencies

​
Advanced Options

​
Default Version Type

Set the default version type for all projects: 
MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE: beta
ValueIncludes
releaseRelease versions only (default)
betaRelease and beta versions
alphaRelease, beta, and alpha versions

​
Custom Loader

When using a custom server type, specify which loader type for lookups: 
MODRINTH_LOADER: fabric

​
Complete Example

1

Create docker-compose.yml

services:
  minecraft:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
      TYPE: FABRIC
      VERSION: "1.21.4"
      MODRINTH_PROJECTS: |
        fabric-api
        lithium:beta
        ferritecore
        cloth-config:17.0.127
        datapack:terralith
      MODRINTH_DOWNLOAD_DEPENDENCIES: required
      MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE: release
    volumes:
      - minecraft-data:/data
    ports:
      - "25565:25565"

volumes:
  minecraft-data:
2

Start the server

docker compose up -d
The container will:
  1. Download fabric-api (latest release)
  2. Download lithium (latest beta)
  3. Download ferritecore (latest release)
  4. Download cloth-config version 17.0.127
  5. Download terralith datapack
  6. Download required dependencies
  7. Start the server
3

Update a mod version

Edit docker-compose.yml to update lithium to latest release:
MODRINTH_PROJECTS: |
  fabric-api
  lithium  # Changed from lithium:beta
  ferritecore
  cloth-config:17.0.127
  datapack:terralith
Restart the container:
docker compose up -d
The old beta version is automatically removed and the latest release is downloaded.

​
Environment Variables Reference

VariableDescriptionDefault
MODRINTH_PROJECTSComma/newline separated list of projectsNone
MODRINTH_DOWNLOAD_DEPENDENCIESDependency download mode: none, required, optionalnone
MODRINTH_PROJECTS_DEFAULT_VERSION_TYPEDefault version type: release, beta, alpharelease
MODRINTH_LOADERLoader type for custom serversAuto-detected
VERSION_FROM_MODRINTH_PROJECTSAuto-detect VERSION from projectsfalse
Changing MODRINTH_PROJECTS and restarting will automatically add new mods and remove old ones. Always backup your data before making changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us