Installation

How to download, install, and configure MekHQ on Windows and Mac

On This Page

Prerequisites
Downloading MekHQ
Extracting the Archive
Folder Structure
First Launch
After Installation
Optional Configuration
User Files Directory
Moving Campaigns Between Versions
Reporting Issues

Prerequisites

MekHQ requires Java 17 or newer to run. Install Java before downloading MekHQ.

Windows

Follow the Java installation instructions on the Downloads page (displayed prominently).

Tip: The Adoptium Temurin installer is recommended.

Mac

Install Java 17 LTS via the Adoptium Temurin package installer.

Supports both Intel (x64) and Apple Silicon M-Series (aarch64).

32-bit Systems

32-bit machines must use Java 17 LTS specifically. Java 21+ dropped 32-bit support entirely.

Downloading MekHQ

Download the MekHQ Suite from our Downloads page. The suite includes MegaMek (battles) and MegaMekLab (unit editor) in one package.

Release Types

Release Type	Description	Recommended For
Milestone	Stable, polished version considered most reliable by developers	Most players
Development	Feature-complete with newer features, may contain bugs	Testing new features
Nightly Builds	Latest development from GitHub	Advanced users reporting bugs

Extracting the Archive

MekHQ uses .tar.gz archives—a single download that works on Windows, Mac, and Linux.

Windows

Use 7-Zip

The Windows built-in extractor struggles with MekHQ's 16,000+ files and can fail or corrupt the extraction. Download 7-Zip (free).

Extract to a simple path like C:\Games\MekHQ (avoid paths with spaces or special characters).

Mac

Avoid Protected Folders

Do NOT use: Downloads, Documents, or Desktop. macOS security prevents MegaMek from running in these locations.

Create a Games folder in your home directory: ~/Games/MekHQ

iCloud Warning: If iCloud syncs protected folders, files may be deleted locally.

Folder Structure

After extraction, your folder should contain:

MekHQ/
├── bin/                  Program binaries
├── campaigns/            ← Save files go here
├── data/                 Game data files
├── docs/                 ← Documentation (important!)
├── lib/                  Java libraries
├── logs/                 Log files for troubleshooting
├── mmconf/               Configuration files
├── userdata/             User customizations
├── MegaMek.exe           Tactical battle simulator
├── MegaMek.l4j.ini       MegaMek memory settings
├── MegaMekLab.exe        Unit editor
├── MegaMekLab.l4j.ini    MegaMekLab memory settings
├── MekHQ.exe             ← Campaign manager (start here)
├── MekHQ.l4j.ini         MekHQ memory settings
├── 


sentry.properties SentryAnonymous error reporting system that helps developers fix bugs quickly.Click for full definition
      ← Error reporting (opt-in)
└── SubmitBug.html        Bug reporting instructions

Documentation & Rules

The docs folder contains extensive documentation on MekHQ features, especially those not covered in official rulebooks (like personnel turnover and StratCon).

MegaMek and MegaMekLab implement rules from the core BattleTech rulebooks: Total Warfare, TechManual, BattleMech Manual, Tactical Operations, Strategic Operations, Interstellar Operations, and Campaign Operations. These programs stay extremely close to the official rules.

MekHQ draws primarily from Campaign Operations, supplemented by systems inspired by A Time of War (the RPG), various sourcebooks, and canon from the novels.

Important: Due to copyright, we cannot reproduce the rules themselves—though we include tooltips with page references where possible. These programs assume familiarity with BattleTech tabletop rules. Without that foundation, the already steep learning curve becomes significantly steeper.

First Launch

Windows

Double-click the executable to launch:

`MekHQ.exe`	Campaign management
`MegaMek.exe`	Tactical battles
`MegaMekLab.exe`	Unit customization

Mac

First run requires Gatekeeper bypass:

Right-click (or Control-click) the JAR file
Select "Open" from the menu
Click "Open" in the security dialog

After updates: Repeat this process for each new version.

You're Ready!

MekHQ should now launch. Continue to Campaign Setup to start your first campaign, or explore the optional configuration sections below.

After Installation

Optional Configuration

These settings can be configured at any time:

Anonymous Error Reporting

Help developers fix bugs by enabling Sentry SentryAnonymous error reporting system that helps developers fix bugs quickly.Click for full definition , our anonymous error reporting system.

Edit sentry.properties and change enabled=false to enabled=true.

Memory Allocation

Increase memory allocation if needed for larger games.

Edit the .l4j.ini files. See the FAQ for details.

User Files Directory

Highly Recommended

Setting up a User Files Directory is one of the most helpful things you can do when using MegaMek. It makes upgrading between versions painless—just point your new installation to the same folder and all your custom content is instantly available.

Take 5 minutes to set this up now and save yourself hours of frustration later!

Set up a custom folder for your personal content (camos, portraits, custom units) that persists between updates and works across all three programs.

Why Use a User Directory?

Centralized Storage

Keep all customizations in one place instead of scattered across multiple installations.

Easy Upgrades

Point new installations to your user folder—no need to copy files each time.

Multi-Version Access

Share resources across different versions without duplication.

Cloud Compatible

Works with OneDrive, Dropbox, or Google Drive (files must sync locally).

Configuration by Program

Program	How to Set
MekHQ	File > MekHQ Options > Miscellaneous > User Files Directory
MegaMek	View > Client Settings > User Files Directory
MegaMekLab	File > Options > User Files Directory

Set the path to a folder outside your installation (e.g., C:\Games\MegaMek_UserData). Restart the program after changing.

Required Folder Structure

MegaMek_UserData/
├── *.ttf                       Fonts (anywhere in root)
├── *.mtf, *.blk                Custom units (anywhere in root)
└── data/
    ├── campaignPresets/        Campaign preset files
    ├── images/
    │   ├── camo/               Camouflage patterns
    │   ├── portraits/          Personnel portraits
    │   └── fluff/
    │       ├── Mek/            Mek fluff images
    │       ├── Vehicle/        Vehicle fluff images
    │       └── ...             Other unit types
    └── universe/
        ├── ranks.xml           Custom rank definitions
        └── awards/             Custom award .xml files

Limitation

Map boards cannot be stored in the user directory due to program load mechanics. Keep boards in your installation's data/boards/ folder.

Video Tutorial: Upgrading MekHQ

MekHQ Tutorial — Upgrading MekHQ Versions

Moving Campaigns Between Versions

Critical: Treat Each Release as Stand-Alone

MekHQ is NOT backward compatible. Once a campaign is loaded in a newer version, it cannot be opened in older versions. Copy, never move your data forward.

Always keep your original campaign files intact—never move or overwrite them.

MekHQ Campaigns

ARE transferable between versions when you follow the migration steps below. Campaigns can move forward to newer versions (but never backward).

MegaMek Saves

Are generally NOT transferable between versions. Complete any in-progress battles before upgrading—don't expect to continue MegaMek saves in a new version.

Step-by-Step Migration

Make a Backup

This is the most critical step to prevent data loss! Copy your campaign files (.cpnx) and any custom files to a safe backup location before proceeding.

Install New Version Separately

NEVER overwrite the existing folder. Extract the new version to a different location—always keep each version in its own folder.

Copy Campaign Files

Copy (not move!) your .cpnx files to the new version's campaigns folder.

Do NOT Copy These

Never copy MegaMek saves or any preference files from a different version—they cause compatibility issues and can corrupt your installation.

Re-save Custom Presets

If you use custom campaign presets, re-save them in the new version to ensure they're updated with the new version's settings.

Best Practice

Keep your old installation until you've verified everything works in the new version. This gives you a fallback if anything goes wrong.

Reporting Issues

If you find a bug or want to suggest an enhancement:

MekHQ: Use the Built-In Bug Reporter

MekHQ includes a "Report a Bug" button that makes submitting issues easy. Access it via Help > Report a Bug.

This feature creates a special save file that automatically bundles:

Your campaign save file
All log files from your session
Any custom unit files used in your campaign

This means you no longer need to manually gather and upload custom units separately—everything developers need is packaged automatically!

Discuss on Discord First

Developers may already be working on it. Join us on Discord.

Choose the Correct Tracker

Issue Type	Tracker
Battle engine bugs	MegaMek Issues
Unit editor bugs	MegaMekLab Issues
Campaign management bugs	MekHQ Issues
Unit data errors (stats, costs)	MegaMek-Data Issues

Submit Your Report

Check for duplicates before submitting
Follow the template - Clear information helps resolve issues faster
Tag feature requests with "RFE" in the title
Attach files - Campaign saves, log files, and screenshots help tremendously