Installing and Migrating

This page shows how to install, update, or migrate a GTNH client.

• For compatible mods, see Additional Mods,
• For texture packs, see Resource Packs,
• For backups, see Backups and Recovery (already included for singleplayer),
• For server installation and updates, see Server Setup.
• For nightly testing builds, see Nightly builds.

Installing

edit 

Lost?

Any of these computer terms drawing a blank? Not sure what the difference is between a JDK, JRE or Java SE?

• Check out the Lexicon

For all launchers:

• GTNH requires a valid Minecraft account & Microsoft Login
• 5-7 GB of memory (RAM) is recommended for Single Player (SP).
  • Ensure there's still enough free RAM available for the operating system.
  • Assign the total memory allocation for both minimum and maximum in the launcher.
  • Allocating more than 8GB with Java8 will likely cause serious stuttering due to poor default garbage collection optimization.
• It's strongly encouraged to install the latest stable release -- currently 2.5.1
• For multiplayer servers (MP), your GTNH client modpack needs to be of the same version as the server

If you want to play on the more experimental dev releases for testing or to get the latest features, you can check Dev Release Stability to see if they have serious problems. Even if you don't plan to play a dev build, that page will list any critical current issues, so have a look.

MultiMC or Prism Launcher with Java 17-21

At the moment, newer Java versions can only be used with MultiMC or Prism Launcher.

1. Install MultiMC or Prism Launcher. If you are on Windows 10 or 11, make sure you are not installing it in a OneDrive folder!
   1. Register your Minecraft account with the launcher. It must run in online mode at least once to authenticate.
2. Java 21 can be downloaded for example from Adoptium. Go to "Other platforms and versions", pick the JRE that matches your computer's OS and architecture. Unpack and install it. If you don't get an installer in your download, check that you haven't grabbed a JDK by mistake.
   1. Typical Windows file path: C:/Program Files/Eclipse Adoptium/jre-17.0.9.9-hotspot/bin/javaw.exe
   2. Typical MacOS file path: /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home/bin/java
3. Download a MMC/Prism Java17-21 version of the pack from http://downloads.gtnewhorizons.com/Multi_mc_downloads/ (they might currently be labelled as java17-20). Do not unzip. Drag it into the MultiMC/Prism window to create the instance.
4. Under Settings > Java, make sure you are using a newly downloaded version of Java; 64-bit Java 17+.
   1. In the case of Java 17 make sure you are updated to at least 17.0.6, older variants can cause start-up errors.
   2. If the Java path: says anything about Java 8 or testing fails, hit the [...] button and manually set the filepath.
   3. Individual instances can also be assigned a specific Java version, arguments and memory allocation. Right-click the instance icon, choose Edit > Settings > Java.
5. If you are using MultiMC you also need to add the additional Java arguments from here for 2.5.1 or older or here for 2.6.0-nightly/beta or newer. You only want the Java args from that page, nothing else. This step is not needed in Prism.

MultiMC with Java 8

1. Install MultiMC. If you are on Windows 10 or 11, make sure you are not installing it in a OneDrive folder!
2. Download a MMC version of the pack from http://downloads.gtnewhorizons.com/Multi_mc_downloads/ and drag it into the MultiMC window to create the instance, or use the "Add Instance" button in the main window.
3. Under settings - Java, make sure you are using a version of 64-bit Java 8.

Technic

1. Install the Technic launcher,
2. In the launcher, go to the Modpacks tab and enter "GT New Horizons" in the search box. Make sure the pack named "GT New Horizons" is selected in the results list.
3. Optionally, click the Modpack settings link in the upper-right to select a specific version and the installation path. By default, the latest stable release will be installed, but some servers may need a different version.
4. Click the Install button on the lower right to install the pack.
5. Go to the Launcher settings at the top-right corner, and the Java tab of that dialog. Make sure you are using an up to date, 64-bit Java 8.

Curseforge Launcher

The Curseforge launcher is not recommended because:

• it usually is out-of-date,
• it constantly messes up recipes,
• its new license requirements on mods make things even worse.

Please do not use a Curseforge launcher for GTNH.

Java Arguments for Java 8

GTNH runs best with configured Java arguments for targeted garbage collection and memory usage. Optimal arguments will vary depending on hardware, launcher and build version. The best performance gains are by going to Java 17-21, not by tweaking Java 8.

• A History of Modded Minecraft Memory Usage
• Modded Minecraft Performace Benchmarks
• Low End PCs

These optimizations are tailored for the Java 8 version of GT:NH. If playing on the Java 17-21 version of the modpack, no additional Java arguments for performance should be needed.

Troubleshooting

• If you are experiencing issues with fullscreen mode, set a resolution in your launcher and check other settings in the config/lwjgl3ify.cfg config file.
• If you get a Windows Firewall window that pops up it is ok to click "Allow Access" for your launcher.

Updating

The direct process

1. Backup your GTNH instance to port settings and configs later. It is done by cloning the instance in the launcher.
   1. In ATLauncher, select Edit Instance > Clone Instance in the drop-down. Select the Open Folder button for a new instance.
   2. In MultiMC, select Copy Instance in the drop-down.
   3. In Prism, right-click on the instance icon, choose Copy
2. Rename the new instance with the GT:NH version being upgraded to.
3. Delete the folders config and mods from Instances/instance_name/.minecraft/. Also delete the folders scripts and resources if you have them and they contain anything. On newer versions they don't exist anymore or are empty.
4. Replace the deleted config and mods folders with the ones from the downloaded archive. They are contained in a .minecraft folder after unpacking. If you are on Mac or Linux, you may have to show hidden files for your OS.
5. If you are using Java 17-21, you also need to replace the folders libraries and patches and the file mmc-pack.json in Instances/instance_name/. Furthermore, if you are using Java 17-21 with MultiMC you might also need to update the required Java Arguments.

The alternative approach

Your alternative is to follow the instruction under installing above to set up a new instance. Then follow the migrating section below to copy your existing world to the new instance.

Migrating to a Different Launcher

Follow the installation instructions for the new launcher, then set up a new instance. Ensure the launcher can run GTNH without issues. Then migrate the files listed below to import your old world. It is highly recommended to keep your old launcher and files around for a while as a backup.

Files to Copy when Migrating or Backing Up

1. /saves/folder.
2. /journeymap/ folder.
3. /visualprospecting/ folder. Ore vein data for JourneyMap.
4. /TCNodeTracker/folder. Thaumcraft node data for JourneyMap.
5. localconfig.cfg file. This keeps track of your local config changes.
6. options.txt.
7. optionsnf.txt or optionsof.txt if you use Angelica or Optifine, respectively.
8. /serverutilities/ folder, if ServerUtilities is installed. This contains its configs and rank settings.
9. /schematics/ folder. If you use Schematica, this is where your saved schematics are.
10. BotaniaVars.dat - this NBT file holds your Lexica Botania bookmarks and other global stuff Botania tracks.
11. /resourcepacks/ or /screenshots/ if you want to keep what you have there.
12. Any custom mods you want to keep and data related to them. For example the /local/ folder, if you use FTBUtilities.
13. Your backups in the /backups/ folder (not needed if you keep the old instance for a bit).