Auto CurseForge

To manage a CurseForge modpack automatically with upgrade support, pinned or latest version tracking, set MODPACK_PLATFORM, MOD_PLATFORM or TYPE to AUTO_CURSEFORGE. The appropriate mod loader (Forge/Fabric) version is automatically installed as declared by the modpack. This mode also cleans up unused files from previous versions, but world data is never auto-removed.

API Key Required

A CurseForge API key is required to use this feature. Go to the CurseForge Developer Console, generate an API key, and set the environment variable CF_API_KEY.

Escaping Dollar Signs

When entering your API key in a Docker Compose file, escape any $ character with a second $:

compose.yaml

environment:
  CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa'

With docker run, use single quotes:

docker run ... -e CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'

Using .env Files (Recommended)

To avoid exposing the API key, use a .env file which is loaded automatically by Docker Compose.

Create .env file

Create a .env file in the same directory as your compose.yaml:

CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'

You do not need to escape $ characters in the .env file when wrapped in single quotes.

Reference in compose file

compose.yaml

environment:
  CF_API_KEY: ${CF_API_KEY}

File structure

Your directory should look like:

minecraft-server/
├── .env
├── compose.yaml
├── data/

For docker run, specify the .env file explicitly:

docker run --env-file=.env itzg/minecraft-server

Using Docker Secrets

Alternatively, use Docker secrets:

compose.yaml

services:
  mc:
    environment:
      CF_API_KEY_FILE: /run/secrets/cf_api_key
    secrets:
      - cf_api_key

secrets:
  cf_api_key:
    file: cf_api_key.secret

Environment Variables

Variable	Required	Description
`TYPE`	Yes	Set to `AUTO_CURSEFORGE`
`CF_API_KEY`	Yes	CurseForge API key
`CF_PAGE_URL`	*	Modpack or file page URL
`CF_SLUG`	*	Modpack slug from URL
`CF_FILE_ID`	No	Numerical file ID for specific version
`CF_FILENAME_MATCHER`	No	Substring to match desired filename
`CF_MODPACK_ZIP`	No	Container path to unpublished modpack ZIP
`CF_MODPACK_MANIFEST`	No	Container path to modpack manifest JSON
`CF_EXCLUDE_MODS`	No	Comma/space delimited list of mod slugs/IDs to exclude
`CF_FORCE_INCLUDE_MODS`	No	Comma/space delimited list of mod slugs/IDs to include
`CF_EXCLUDE_ALL_MODS`	No	Exclude all mods (default: `false`)
`CF_EXCLUDE_INCLUDE_FILE`	No	Path to JSON file with exclude/include rules
`CF_OVERRIDES_EXCLUSIONS`	No	Ant-style paths to exclude from overrides
`CF_IGNORE_MISSING_FILES`	No	Glob pattern of files to ignore if missing
`CF_SET_LEVEL_FROM`	No	Set LEVEL from `WORLD_FILE` or `OVERRIDES`
`CF_PARALLEL_DOWNLOADS`	No	Number of parallel downloads (default: 4)
`CF_OVERRIDES_SKIP_EXISTING`	No	Skip existing files in overrides (default: `false`)
`CF_FORCE_SYNCHRONIZE`	No	Force re-evaluation of excludes/includes
`CF_FORCE_REINSTALL_MODLOADER`	No	Force modloader reinstall (default: `false`)
`CF_DOWNLOADS_REPO`	No	Path for manual downloads (default: `/downloads`)
`CF_MOD_LOADER_VERSION`	No	Override mod loader version

Either CF_PAGE_URL or CF_SLUG is required to identify the modpack

Specifying the Modpack

Using Page URL

Pass the modpack page URL or a specific file URL:

environment:
  MODPACK_PLATFORM: AUTO_CURSEFORGE
  CF_API_KEY: ${CF_API_KEY}
  CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8

Using Slug

The slug is the short identifier in the URL after /modpacks/:

environment:
  MODPACK_PLATFORM: AUTO_CURSEFORGE
  CF_API_KEY: ${CF_API_KEY}
  CF_SLUG: all-the-mods-8

Pinning Versions

By default, the latest modpack file and mod loader are installed on startup (with automatic upgrading). To pin to a specific version:

Using File ID

CF_SLUG: all-the-mods-8
CF_FILE_ID: "4248390"

Using Filename Matcher

CF_SLUG: all-the-mods-8
CF_FILENAME_MATCHER: 1.0.7

Using Specific File URL

CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390

Do not select a server file - they lack the required manifest and defeat automation capabilities. Always use client files.

Examples

services:
  mc:
    image: itzg/minecraft-server:java17
    ports:
      - "25565:25565"
    environment:
      EULA: "true"
      MODPACK_PLATFORM: AUTO_CURSEFORGE
      CF_API_KEY: ${CF_API_KEY}
      CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
      MEMORY: 4G
    volumes:
      - mc-data:/data

volumes:
  mc-data:

Custom Mod Loader Versions

Override the modpack’s declared mod loader version:

environment:
  CF_MOD_LOADER_VERSION: "43.4.22"

Using a custom mod loader version that differs significantly from the modpack’s design may cause compatibility issues. Use carefully and test thoroughly.

Manual Downloads

For mods/modpacks not allowed for automated download, attach the /downloads container path:

Create downloads directory

Create a directory next to compose.yaml. Common convention is downloads

Download files

Use a browser to download files listed in “Mods Need Download” output

Mount the directory

volumes:
  - ./data:/data
  - ./downloads:/downloads

Restart

docker compose up -d

It’s important to use a browser to download the files. If your Docker host is running without a graphical interface, use scp or similar to transfer files.

The subdirectories mods, modpacks, and worlds are also checked. To change the location, set CF_DOWNLOADS_REPO. To disable, set it to an empty string.

Unpublished Modpacks

For unpublished modpack ZIPs or custom manifests:

services:
  mc:
    image: itzg/minecraft-server:latest
    environment:
      EULA: true
      MODPACK_PLATFORM: AUTO_CURSEFORGE
      CF_API_KEY: ${CF_API_KEY}
      CF_MODPACK_MANIFEST: /manifests/manifest.json
      CF_SLUG: "custom"
    volumes:
      - ./data:/data
      - ./manifests:/manifests:ro

The modpack slug or page URL must still be provided even when using CF_MODPACK_ZIP or CF_MODPACK_MANIFEST.

Excluding Client Mods

Exclude mods that aren’t server-compatible:

environment:
  CF_EXCLUDE_MODS: |
    # Exclude client-side mods not published correctly
    creative-core
    default-options

Comments can be embedded in the list using the # character.

For complex scenarios, use a JSON exclude/include file:

environment:
  CF_EXCLUDE_INCLUDE_FILE: /config/exclude-include.json

The schema is documented here. By default, the bundled file is used.

Finding Project IDs

A mod’s project ID is shown on the right side of the project page.

Force Including Mods

For mods incorrectly tagged as client-only:

environment:
  CF_FORCE_INCLUDE_MODS: sophisticated-backpacks,jade

CF_FORCE_INCLUDE_MODS will not download additional mods. For additional mods, use the CURSEFORGE_FILES variable.

Excluding Overrides Files

Modpack ZIPs include an overrides subdirectory with config files, world data, and extra mods. Exclude specific files using ant-style paths:

environment:
  CF_OVERRIDES_EXCLUSIONS: |
    mods/iris*.jar
    mods/sodium*.jar

Ant-style Path Patterns

Symbol	Behavior
`*`	Matches zero, one, or many characters except a slash
`**`	Matches zero, one, or many characters including slashes
`?`	Matches one character

World/Level Data

Some modpacks include world data via worlds file or overrides. Set the LEVEL automatically:

environment:
  CF_SET_LEVEL_FROM: WORLD_FILE
  # or
  CF_SET_LEVEL_FROM: OVERRIDES

Ignoring Missing Files

Some mods use temporary files that get deleted, like gregtech. Prevent re-installation:

environment:
  CF_IGNORE_MISSING_FILES: |
    mods/gregtech-2.6.2-beta.jar
    mods/*.jar

A warning log will indicate missing files:

Re-installing due to missing files from modpack: [mods/gregtech-2.6.2-beta.jar]

Extra Options

Parallel Downloads

Control concurrent mod downloads:

CF_PARALLEL_DOWNLOADS: 8

Skip Existing Overrides

Skip files in overrides that already exist:

CF_OVERRIDES_SKIP_EXISTING: "true"

World data is always skipped if present.

Force Reinstall Modloader

Force modloader reinstallation if files are corrupted:

CF_FORCE_REINSTALL_MODLOADER: "true"

Troubleshooting

If exclude/include changes aren’t taking effect, set CF_FORCE_SYNCHRONIZE to true to force re-evaluation.

Most modpacks require significant memory. Set MEMORY to at least 4G.

Be sure to use the appropriate image tag for the Java version compatible with the modpack.

Get Started

Server Types

Mod Platforms

Configuration

Mods & Plugins

Versions

Operations

Deployment

Advanced

API Key Required

Escaping Dollar Signs

Using .env Files (Recommended)

Using Docker Secrets

Environment Variables

Specifying the Modpack

Using Page URL

Using Slug

Pinning Versions

Using File ID

Using Filename Matcher

Using Specific File URL

Examples

Custom Mod Loader Versions

Manual Downloads

Unpublished Modpacks

Excluding Client Mods

Finding Project IDs

Force Including Mods

Excluding Overrides Files

Ant-style Path Patterns

World/Level Data

Ignoring Missing Files

Extra Options

Parallel Downloads

Skip Existing Overrides

Force Reinstall Modloader

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Server Types

Mod Platforms

Configuration

Mods & Plugins

Versions

Operations

Deployment

Advanced

​API Key Required

​Escaping Dollar Signs

​Using .env Files (Recommended)

​Using Docker Secrets

​Environment Variables

​Specifying the Modpack

​Using Page URL

​Using Slug

​Pinning Versions

​Using File ID

​Using Filename Matcher

​Using Specific File URL

​Examples

​Custom Mod Loader Versions

​Manual Downloads

​Unpublished Modpacks

​Excluding Client Mods

​Finding Project IDs

​Force Including Mods

​Excluding Overrides Files

​Ant-style Path Patterns

​World/Level Data

​Ignoring Missing Files

​Extra Options

​Parallel Downloads

​Skip Existing Overrides

​Force Reinstall Modloader

​Troubleshooting

Build docs developers (and LLMs) love

API Key Required

Escaping Dollar Signs

Using .env Files (Recommended)

Using Docker Secrets

Environment Variables

Specifying the Modpack

Using Page URL

Using Slug

Pinning Versions

Using File ID

Using Filename Matcher

Using Specific File URL

Examples

Custom Mod Loader Versions

Manual Downloads

Unpublished Modpacks

Excluding Client Mods

Finding Project IDs

Force Including Mods

Excluding Overrides Files

Ant-style Path Patterns

World/Level Data

Ignoring Missing Files

Extra Options

Parallel Downloads

Skip Existing Overrides

Force Reinstall Modloader

Troubleshooting