installation.html

---
layout: page
title: Installation and Updating
---

<div class='row'>
  <div class='col'>
    <h3>Installation Instructions</h3>
  </div>
</div>
<div class='row'>
  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        Installing Java
      </div>
      <div class='card-body'>
        <p class='card-text'>
          Java is required for use of this program and we recommend using
          Adoptium 17 for current and future versions for best results.
          Starting with the 0.50.0 development release, it will be required.
        </p>
        <p>
          MegaMek should run on any computer that can run Java without much
          issue. Will NOT run on iOS/iPadOS/tvOS/Android devices. You
          experience will vary based on computer specifications.
        </p>
        <p class='card-text'>
          Instructions for <a href='https://github.com/MegaMek/megamek/wiki/Updating-to-Adoptium-(Eclipse-Temurin-Open-Source-Java)'>Windows</a>
          and <a href="/wiki/mac_issues.html">macOS</a> are available.
        </p>
        <div class="ratio ratio-16x9 mt-3">
          <iframe src="https://www.youtube.com/embed/le43AxvqHTc?si=ll1bZMBLMZ-IgysG" title="MekHQ Tutorial - Installing Java" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
        </div>
      </div>
    </div>
  </div>
</div>

<div class="row mt-4">
  <div class="col">
    <div class="card dl-card" style="border: 3px solid #ffc107; border-radius: 12px;">
      <div class="card-header" style="border-bottom: 2px solid #ffc107;">
        <h4 class="mb-0" style="color: #ffc107;"><i class="fas fa-exclamation-triangle"></i> Updating Between Versions</h4>
      </div>
      <div class="card-body">
        <!-- Critical Warning Banner -->
        <div class="text-center p-3 mb-4" style="border: 2px solid #dc3545; border-radius: 8px;">
          <p class="mb-0" style="color: #e0e0e0;">
            <strong style="color: #dc3545;"><i class="fas fa-exclamation-circle"></i> CRITICAL:</strong> Always extract each version to its own folder — never unzip a new version over an old one (e.g., don't extract 0.50.11 into your 0.50.06 folder). Overwriting <strong style="color: #dc3545;">will corrupt saves and campaigns</strong>. Campaigns are also <strong style="color: #dc3545;">NOT backward compatible</strong>; if a newer campaign opens in an older version, consider yourself lucky.
          </p>
        </div>

        <!-- Steps -->
        <p style="color: #e0e0e0; margin-bottom: 1rem;">
          Follow these steps to protect your MekHQ campaign data:
        </p>
        <ol style="color: #e0e0e0; line-height: 1.8;">
          <li><strong style="color: #fff;">Back up your campaign and custom files</strong> — critical to prevent data loss</li>
          <li><strong style="color: #fff;">Extract the new version to a fresh folder</strong> — never overwrite the old installation</li>
          <li><strong style="color: #fff;">COPY</strong> (don't move) your campaigns and custom data to the new folder</li>
          <li><strong style="color: #fff;">Do NOT copy</strong> MegaMek saves or preference files between versions</li>
          <li><strong style="color: #fff;">Re-save custom presets</strong> to update them for the new version</li>
        </ol>
      </div>
    </div>
  </div>
</div>

<div class="row row-cols-3 mt-4">
  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        macOS and MegaMek
      </div>
      <div class='card-body'>
        <p class='card-text'>
          For those of us using macOS, there are some additional things that
          we need to be aware of. We're making this more prominent in hopes
          to reduce the number of questions we get that can be solved by
          going <a href="/wiki/mac_issues.html">here</a>.
        </p>
        <p class='card-text'>
          Make sure Adoptium 17 is installed. Recommended way is in the link
          above.
        </p>
        <p class='card-text'>
          Make sure the decompressed files are <em><strong>NOT</strong></em>
          in the <strong>Documents</strong>, <strong>Downloads</strong>,
          or <strong>Desktop</strong> folders. These are
          <em><strong>protected</strong></em> folders and macOS will not
          let it run.
        </p>
      </div>
    </div>
  </div>

  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        Windows
      </div>
      <div class='card-body'>
        <p class='card-text'>
          To run the programs from Windows, just double-click on the given
          program icon from within the folder you unzipped.
        </p>
        <p class='card-text'>
          Depending on how Java is setup on your machine, you may also be able
          to double click on the JAR files themselves vs the EXE. No real
          difference between the two other than possible launching experience.
        </p>
        <p class='card-text'>
          <strong><em>DO NOT USE THE BUILTIN UTILITY FOR DECOMPRESSING ZIP FILES!</em></strong>
          We recommend using <a href='https://www.7-zip.org'>7-Zip.</a>
        </p>
      </div>
    </div>
  </div>

  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        Unix/Linux
      </div>
      <div class='card-body'>
        <p class='card-text'>
          The Unix/Linux releases do not include application binaries, but
          you can run the programs directly from the included JAR files. On
          some desktops, you may just be able to double-click these JAR
          files in order to run the programs. you can also run the programs
          (MegaMek, in the example below) from the command line with the
          command:

        <div class="language-bash highlighter-rouge">
          <div>
            <pre class="highlight"><code>java <span class="nt">-jar</span> MegaMek.jar &amp;</code></pre>
          </div>
        </div>
        </p>
      </div>
    </div>
  </div>

  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        Milestone vs. Development
      </div>
      <div class='card-body'>
        <p class='card-text'>
          We recommend that most users download and use the milestone version of
          the programs to minimize issues with bugs. The development versions
          are only for those users interested in testing and bug hunting new
          features.
        </p>
      </div>
    </div>
  </div>

  <div class='col mb-4'>
    <div class='card dl-card'>
      <div class='card-header'>
        Installation and Running
      </div>
      <div class='card-body'>
        <p class='card-text'>
          To install the programs, unzip the download into the directory of
          your choice. To run the programs follow the platform specific
          instructions below.
        </p>
        <p>
          On Windows, do <strong>NOT</strong> use the built in utility for
          decompression zip files as it has been known to cause issues.
          We recommend using <a href='https://www.7-zip.org'>7-Zip</a>.
        </p>
      </div>
    </div>
  </div>
</div>