Configuration Reference

Configuration Files

Essential Loader uses two types of configuration files:

Container mod configuration: Embedded in the mod jar
User configuration: Stored in the game directory

Container Mod Configuration

Location: Root of the container jar

container-mod.jar
├── essential-loader.properties  ← Container configuration
├── bundled-mod.jar
└── ...

Defines default behavior and mod metadata. Distributed with the mod.

User Configuration

Location: .minecraft/essential/mods/$pub_$mod/essential-loader.properties Where:

$pub = publisherSlug from container configuration
$mod = modSlug from container configuration
If both are identical, shortened to just $mod

Special case: Essential itself uses .minecraft/essential/essential-loader.properties for legacy compatibility.

Overrides container settings on a per-user basis. Created programmatically or manually by users.

Container Configuration Properties

Required Properties

publisherSlug

string

required

The publisher slug as configured in the Essential Mods Panel.Used to:

Identify the mod publisher
Construct API endpoints
Determine user configuration location

Example: essential

modSlug

string

required

The mod slug as configured in the Essential Mods Panel.Used to:

Identify the specific mod
Construct API endpoints
Determine user configuration location

Example: examplemod

displayName

string

required

Human-readable name for UI and log messages.Shown in:

Update prompts
Log output
Error messages

Example: ExampleMod

Optional Properties

publisherId

string

The publisher ID from the Essential Mods Panel.Optional identifier that may be used instead of slug in certain API calls.Example: 26d49e5b60ecf53d6b26c76a

modId

string

The mod ID from the Essential Mods Panel.Optional identifier that may be used instead of slug in certain API calls.Example: 60ecf53d6b26c76a26d49e5b

branch

string

default:"stable"

The default update branch for this mod.Common values:

stable: Production releases
beta: Beta channel
staging: Development builds

Can be overridden by user configuration.

Pinning Properties

See Pinning Documentation for detailed information.

pinnedFile

string

Path to the embedded mod jar inside the container jar.Must start with / to be read as a jar resource (e.g., /bundled-mod-1.0.0.jar).Without leading slash, it’s treated as a URL.

pinnedFileMd5

string

MD5 checksum of the pinned jar file.Required when pinnedFile is set. Used to verify integrity.Example: d41d8cd98f00b204e9800998ecf8427e

pinnedFileVersion

string

Version string of the pinned jar.Recommended when using pinning. Required for:

Click-to-update functionality
Diff-updates
Version-aware mods

Example: 1.2.0

pinnedFileVersionId

string

Version ID from the Essential Mods Panel.Optional. May be used instead of version string in future functionality.Example: 6b26c76a26d49e5b60ecf53d

User Configuration Properties

Update Control

autoUpdate

string

default:"true (or with-prompt if pinned)"

Controls update behavior.Values:

true: Automatic updates on every boot
with-prompt: Check for updates, wait for user consent
false: No automatic update checks

Default:

true for thin container mods
with-prompt for pinned container mods

branch

string

Override the update branch.Overrides the branch specified in container configuration.Example: beta

Update Resolution (Internal)

These properties are managed by the loader and should not be manually edited unless you know what you’re doing.

pendingUpdateVersion

string

Set by the loader when an update is available.Read-only for mods. Do not modify this value directly. Set pendingUpdateResolution instead.Example: 1.2.0.13

pendingUpdateResolution

boolean

Set by the mod to accept or reject the pending update.

true: Download and install update
false: Skip this update
Unset: Waiting for decision

overridePinnedVersion

string

Internal use only. Tracks the last accepted update version.Prevents unwanted downgrades when container mod version changes.Automatically managed by the loader.

Configuration Examples

Thin Container Mod

A lightweight container that always downloads the latest version:

# essential-loader.properties (in jar)
publisherSlug=mycompany
modSlug=awesome-mod
displayName=Awesome Mod
branch=stable

No pinned properties = thin container.

Pinned Container Mod

Embeds a specific version with click-to-update:

# essential-loader.properties (in jar)
publisherSlug=mycompany
modSlug=awesome-mod
displayName=Awesome Mod
branch=stable

pinnedFile=/awesome-mod-2.1.0.jar
pinnedFileMd5=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
pinnedFileVersion=2.1.0

Default autoUpdate=with-prompt prompts users for updates.

Pinned with Auto-Update Enabled

Embed a version but enable automatic updates by default:

Container Config
User Config

# essential-loader.properties (in jar)
publisherSlug=mycompany
modSlug=awesome-mod
displayName=Awesome Mod
branch=stable

pinnedFile=/awesome-mod-2.1.0.jar
pinnedFileMd5=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
pinnedFileVersion=2.1.0

# .minecraft/essential/mods/mycompany_awesome-mod/essential-loader.properties
autoUpdate=true

Programmatically enable during first launch or via user settings.

Beta Branch Testing

Container Default
Per-User Override

# essential-loader.properties (in jar)
publisherSlug=mycompany
modSlug=awesome-mod
displayName=Awesome Mod
branch=beta

All users follow beta branch.

# User wants to test staging
# .minecraft/essential/mods/mycompany_awesome-mod/essential-loader.properties
branch=staging

Offline/LAN Environment

Disable all update checks:

Container Config
User Config

publisherSlug=company
modSlug=internal-tool
displayName=Internal Tool

pinnedFile=/internal-tool-1.5.0.jar
pinnedFileMd5=abc123def456...
pinnedFileVersion=1.5.0

# .minecraft/essential/mods/company_internal-tool/essential-loader.properties
autoUpdate=false

Combining a pinned jar with autoUpdate=false enables fully offline operation.

Environment Variables

Configuration can be influenced by environment variables:

ESSENTIAL_DOWNLOAD_URL

string

Override the API base URL for downloads.Default: https://api.essential.gg/modsUseful for:

Corporate proxies
Mirror servers
Testing environments

export ESSENTIAL_DOWNLOAD_URL=https://mirror.example.com/mods

ESSENTIAL_STAGE2_BRANCH

string

Override the stage2 update branch.Affects the loader’s own update channel.

export ESSENTIAL_STAGE2_BRANCH=beta

System Properties

JVM system properties provide additional control:

essential.download.url

string

Override the API base URL (same as ESSENTIAL_DOWNLOAD_URL).

java -Dessential.download.url=https://mirror.example.com/mods -jar minecraft.jar

essential.stage2.branch

string

Override stage2 update branch (same as ESSENTIAL_STAGE2_BRANCH).

java -Dessential.stage2.branch=beta -jar minecraft.jar

essential.autoUpdate

string

Override auto-update setting globally.

java -Dessential.autoUpdate=false -jar minecraft.jar

essential.loader.relaunched

boolean

Internal. Indicates if the game was relaunched.Set by the loader to prevent update checks on relaunch.

java -Dessential.loader.relaunched=true -jar minecraft.jar

Configuration Priority

When multiple configuration sources conflict, this priority order applies:

System properties (-Dessential.*)
Environment variables (ESSENTIAL_*)
User configuration file (.minecraft/essential/mods/$pub_$mod/essential-loader.properties)
Container configuration (essential-loader.properties in jar)
Defaults (hardcoded in loader)

Example Conflict
Partial Override

Container config:

branch=stable

User config:

branch=beta

System property:

-Dessential.stage2.branch=staging

Result: staging (system property wins)

Container config:

branch=stable
autoUpdate=true

User config:

branch=beta
# autoUpdate not specified

Result:

branch=beta (user overrides container)
autoUpdate=true (falls back to container)

Stage2 Configuration

Stage2 (the loader’s own loader) has separate configuration:

Container Stage2 Config

Location: gg/essential/loader/stage1/stage2.properties in container jar

pinnedFile=/bundled-stage2-1.0.0.jar
pinnedFileMd5=1a2b3c4d5e6f7890abcdef12
pinnedFileVersion=1.0.0

All three properties are required.

User Stage2 Config

Location: .minecraft/essential/loader/stage1/$variant/config.properties Where $variant is the platform variant (e.g., fabric-1.16.5, forge-1.12.2).

autoUpdate=with-prompt
branch=stable
pendingUpdateVersion=1.0.1
pendingUpdateResolution=true

Same properties as per-mod configuration.

Stage2 pinning is still in development for third-party use. Since stage2 is shared across all mods, complex interaction rules are needed when mods have conflicting pinning preferences.

Best Practices

For Mod Developers

Always include displayName: Makes logs and prompts user-friendly
Use semantic versioning: Enables proper version comparison
Include pinnedFileVersion: Required for diff-updates and click-to-update
Default to with-prompt: Give users control over updates
Implement update UI: Better UX than fallback prompt

For Modpack Authors

Pin specific versions: Ensure consistent user experience
Test updates first: Use beta/staging branches before stable
Document branch choice: Tell users which channel they’re on
Consider offline users: Include pinned jars for offline play

For Server Administrators

Use environment variables: Centrally control update behavior
Consider proxies: Set ESSENTIAL_DOWNLOAD_URL for corporate environments
Disable auto-update: Set essential.autoUpdate=false for controlled environments
Version lock: Use pinned jars with autoUpdate=false

Get Started

Core Concepts

Integration Guides

Advanced

Configuration Files

Container Mod Configuration

User Configuration

Container Configuration Properties

Required Properties

Optional Properties

Pinning Properties

User Configuration Properties

Update Control

Update Resolution (Internal)

Configuration Examples

Thin Container Mod

Pinned Container Mod

Pinned with Auto-Update Enabled

Beta Branch Testing

Offline/LAN Environment

Environment Variables

System Properties

Configuration Priority

Stage2 Configuration

Container Stage2 Config

User Stage2 Config

Best Practices

For Mod Developers

For Modpack Authors

For Server Administrators

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration Guides

Advanced

​Configuration Files

​Container Mod Configuration

​User Configuration

​Container Configuration Properties

​Required Properties

​Optional Properties

​Pinning Properties

​User Configuration Properties

​Update Control

​Update Resolution (Internal)

​Configuration Examples

​Thin Container Mod

​Pinned Container Mod

​Pinned with Auto-Update Enabled

​Beta Branch Testing

​Offline/LAN Environment

​Environment Variables

​System Properties

​Configuration Priority

​Stage2 Configuration

​Container Stage2 Config

​User Stage2 Config

​Best Practices

​For Mod Developers

​For Modpack Authors

​For Server Administrators

Build docs developers (and LLMs) love

Configuration Files

Container Mod Configuration

User Configuration

Container Configuration Properties

Required Properties

Optional Properties

Pinning Properties

User Configuration Properties

Update Control

Update Resolution (Internal)

Configuration Examples

Thin Container Mod

Pinned Container Mod

Pinned with Auto-Update Enabled

Beta Branch Testing

Offline/LAN Environment

Environment Variables

System Properties

Configuration Priority

Stage2 Configuration

Container Stage2 Config

User Stage2 Config

Best Practices

For Mod Developers

For Modpack Authors

For Server Administrators