Skip to main content
Mods and plugins can be auto-downloaded and upgraded from CurseForge by setting CURSEFORGE_FILES to a comma or space delimited list of project-file references. References removed from the declaration are automatically cleaned up. Setting CURSEFORGE_FILES to an empty string removes all previously managed project-files.
CurseForge API key requiredA CurseForge API key must be allocated and set with CF_API_KEY (or CF_API_KEY_FILE) as described in CurseForge modpacks documentation.

​
Project-File References

CurseForge refers to mod/plugin versions broadly as “files” rather than “versions”. Individual project files typically represent a version of the mod/plugin. The following formats are supported:
FormatDescriptionExample
Project page URLAuto-selects newest applicable filehttps://www.curseforge.com/minecraft/mc-mods/jei
File page URLSpecific filehttps://www.curseforge.com/minecraft/mc-mods/jei/files/4593548
Project slugAuto-selects newest applicable filejei
Project IDAuto-selects newest applicable file238222
Project:FileProject slug/ID and file IDjei:4593548 or 238222:4593548
Project@FilenameProject slug/ID and partial filename[email protected]
@Listing filePath to a listing file@/extras/cf-mods.txt
When a specific file is omitted, the newest version is auto-selected based on your server’s VERSION and TYPE.

​
Basic Usage

environment:
  CF_API_KEY: ${CF_API_KEY}
  TYPE: FORGE
  VERSION: "1.20.1"
  CURSEFORGE_FILES: |
    jei
    geckolib
    aquaculture

​
Using Specific Versions

Reference specific file versions using file IDs or partial filenames: 
environment:
  CURSEFORGE_FILES: |
    jei:4593548
    [email protected]
    aquaculture
In this example:
  • jei uses specific file ID 4593548
  • geckolib uses version matching “4.2.4” in the filename
  • aquaculture auto-selects the newest compatible version

​
Using Listing Files

For better organization, use a listing file with one project-file reference per line.
1

Create a listing file

Create cf-mods.txt:
# Core mods
jei:10.2.1.1005
geckolib
aquaculture

# Additional mods
naturalist
Blank lines and lines starting with # are ignored.
2

Mount the file

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

Reference it in CURSEFORGE_FILES

environment:
  CURSEFORGE_FILES: "@/extras/cf-mods.txt"

​
Multi-Line in Docker Compose

Use YAML multi-line strings to organize your mods cleanly: 
services:
  minecraft:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
      CF_API_KEY: ${CF_API_KEY}
      TYPE: FORGE
      VERSION: "1.20.1"
      CURSEFORGE_FILES: |
        jei
        geckolib
        aquaculture
        naturalist
        biomes-o-plenty

​
Dependencies

The files processing can detect if a dependency is missing from your list and will warn you.
CurseForge dependencies cannot be automatically resolved because the metadata only provides the mod ID, not the specific file version/ID needed. You must manually add required dependencies to your CURSEFORGE_FILES list.

​
Complete Example

1

Get a CurseForge API key

Obtain an API key from CurseForge’s developer console.Store it in a .env file:
CF_API_KEY=your-api-key-here
2

Create docker-compose.yml

services:
  minecraft:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
      CF_API_KEY: ${CF_API_KEY}
      TYPE: FORGE
      VERSION: "1.20.1"
      CURSEFORGE_FILES: |
        https://www.curseforge.com/minecraft/mc-mods/jei
        [email protected]
        aquaculture
        238222:4593548
    volumes:
      - minecraft-data:/data
    ports:
      - "25565:25565"

volumes:
  minecraft-data:
This configuration:
  • Downloads JEI (latest compatible version)
  • Downloads Geckolib version matching “4.2.4”
  • Downloads Aquaculture (latest compatible version)
  • Downloads project 238222, file 4593548
3

Start the server

docker compose up -d
Monitor the logs to see mod downloads:
docker compose logs -f
4

Update mods

To update mods to their latest versions, remove version specifiers and restart:
CURSEFORGE_FILES: |
  jei
  geckolib  # Changed from [email protected]
  aquaculture

docker compose up -d

​
Auto-Removal

Mods are automatically removed when you remove them from CURSEFORGE_FILES. Example: Original configuration: 
CURSEFORGE_FILES: |
  jei
  geckolib
  aquaculture
Updated configuration (removed geckolib): 
CURSEFORGE_FILES: |
  jei
  aquaculture
After restart, the geckolib mod will be automatically removed from the mods directory.
Setting CURSEFORGE_FILES to an empty string removes all previously managed project-files:
CURSEFORGE_FILES: ""

​
Finding Project Information

​
Project Slug

The project slug is in the URL: 
https://www.curseforge.com/minecraft/mc-mods/jei
                                              ^^^-- slug

​
Project ID

Find the project ID on the right sidebar of the project page under “About Project”.

​
File ID

Find the file ID in the URL when viewing a specific file: 
https://www.curseforge.com/minecraft/mc-mods/jei/files/4593548
                                                       ^^^^^^^-- file ID
Or find it in the “About” section when viewing a file.

​
Environment Variables Reference

VariableDescriptionRequired
CURSEFORGE_FILESComma/space/newline separated list of project-file referencesYes
CF_API_KEYCurseForge API keyYes
CF_API_KEY_FILEPath to file containing CurseForge API keyAlternative to CF_API_KEY
Use CF_API_KEY_FILE instead of CF_API_KEY for better security with Docker secrets or mounted key files.

Build docs developers (and LLMs) love

Get started for freeTalk to us