# Updating Versions

Source: https://emule-qt.org/help/updating-versions/

## Updating to a new version

An update replaces the program and nothing else. Your settings, credits, shared-file history, unfinished downloads and finished files are kept in a place the new version does not write over, so on most systems updating means installing the new version over the old one. The Windows ZIP is the one exception: there your data sits inside the program folder, so read [its section](https://emule-qt.org/help/updating-versions/#windows-portable) before you unzip anything.

### Where your data lives

| You run | Program | Your data |
|---|---|---|
| **Windows installer** | `C:\Program Files\eMule Qt` | `%LOCALAPPDATA%\eMuleQt`, with `Incoming` and `Temp` inside |
| **Windows ZIP** (portable) | The `eMule` folder you unzipped | The same folder: `config`, `Incoming` and `Temp` next to `emuleqt.exe` |
| **macOS** | `emuleqt.app` in Applications | `~/eMuleQt/Config`, `~/eMuleQt/Incoming`, `~/eMuleQt/Temp` |
| **Linux** | The `eMuleQt` folder from the tarball | `~/eMuleQt/Config`, `~/eMuleQt/Incoming`, `~/eMuleQt/Temp` |
| **Docker** | The image | The `/config` and `/data` volumes |

If you moved Incoming, Temp or your shared folders somewhere else under Options, they stay where you put them. No update touches them.

### Before every update

1. **Quit eMule Qt and its core.** The window and the core (`emulecored`) are two programs. If the chain icon in the status bar is broken, the core is *detached* and keeps running after you close the window. Check that no `emulecored` is left in the Task Manager, the Activity Monitor or `pgrep emulecored`.
2. **Back up your config folder.** It is small, and a copy costs nothing. Unfinished downloads in Temp do not need a backup for a normal update.

## Windows installer

1. **Download the new setup** (`eMuleQt-vX.Y.Z-win64-setup.exe`) from the [download page](https://emule-qt.org/download/).
2. **Run it.** It finds the old install and puts the new version in the same folder. A running eMule Qt and its core are closed for you.
3. **Leave “Import settings from eMule” unticked.** On an update it starts unticked, because your eMule Qt profile is already in use.
4. **Start eMule Qt.**

There is no need to uninstall first. Even if you do, the uninstaller leaves `%LOCALAPPDATA%\eMuleQt` alone.

## Windows ZIP (portable)

In the portable version, your `config` folder is inside the program folder, and the ZIP brings a `config` folder of its own. Here is what the ZIP’s `config` folder contains:

- **Program files that should be replaced:** `eMule.tmpl`, the `webserver` folder, `nodes.ed3knod` and `GeoLite2-Country.mmdb`.
- **Starter files you should keep your own copy of:** `server.met`, `nodes.dat`, `webservices.dat` and `FakeFileFilter.dat`. If the ZIP overwrites them, your server list and Kad contacts go back to the shipped ones. Nothing breaks, but you lose the lists you built up.

None of your personal files are in the ZIP: `preferences.yml`, `preferences.dat`, `cryptkey.dat`, `clients.met`, `known.met`, the `.part` files in Temp and your finished downloads. Unzipping cannot touch them.

### How to update

1. **Quit eMule Qt and its core** (see above).
2. **Unzip the new version into a temporary folder**, not over your install.
3. **In the temporary `eMule\config` folder, delete** `server.met`, `nodes.dat`, `webservices.dat` and `FakeFileFilter.dat`.
4. **Copy everything in the temporary `eMule` folder over your existing `eMule` folder** and confirm that files are replaced.
5. **Start eMule Qt**, then delete the temporary folder.

> **Update in place, do not move**
> 
> It is tempting to unzip into a fresh folder and copy only `config` across. Do not do that. Your unfinished downloads are in `Temp` and your finished files are in `Incoming`, both in the old folder, and `preferences.yml` stores their full paths. A new folder starts with an empty download list, or keeps using the old folder without you noticing. If you really want to move the install, move the **whole** folder and check the directories under Options afterwards.

If you changed the web interface files in `config\webserver`, back them up first: the update replaces them.

## macOS

1. **Quit eMule Qt and its core** (see above).
2. **Open the new disk image**: `eMuleQt-vX.Y.Z-macOS-arm64.dmg` for Apple silicon or `eMuleQt-vX.Y.Z-macOS-x86_64.dmg` for Intel.
3. **Drag eMule Qt into Applications** and choose **Replace**.
4. **Start eMule Qt.**

Your data in `~/eMuleQt` is outside the app and stays as it is.

## Linux

1. **Quit eMule Qt and its core** (see above).
2. **Unpack the new tarball in the same place as the old one**, so it overwrites the old `eMuleQt` folder: `tar xzf eMuleQt-vX.Y.Z-linux-x86_64.tar.gz`
3. **Start eMule Qt.** Your menu entry and file types keep working because the path did not change.

> **Do not delete the old folder first**
> 
> If you unpacked the tarball into your home folder, the program and your data share one folder: the program is `~/eMuleQt` and your data is `~/eMuleQt/Config`, `Incoming` and `Temp`. Deleting the old program folder before the update would delete all of that too. Unpacking over it is always safe, because the tarball has no `Config`, `Incoming` or `Temp` folders. Its lowercase `config` folder holds the shipped defaults, and eMule Qt never copies them over files you have changed.

If you do unpack the new version somewhere else, start it once from there and eMule Qt updates its menu entry to the new path.

## Docker

Pull the new image and recreate the container. Your data lives in the volumes:

- **Docker Compose:** `docker compose pull && docker compose up -d`
- **Plain Docker:** `docker pull ghcr.io/moddermule/emuleqt:latest`, then remove the old container and start a new one with the same `-v` options.

## How you hear about a new version

eMule Qt checks for new versions on its own and shows a box with what has changed and a link to the [download page](https://emule-qt.org/download/). To check right away, use *Tools → Links → Version Check*. If the box says an update is **required**, your version has known serious bugs, and eMule Qt closes until you update.

A core that runs without a window, on a server or a NAS, can install updates by itself: start it as `emulecored --autoupdate`. It downloads each new release, checks it, installs it the way this page describes, keeping your own config files in a portable install too, and restarts with the same options. Docker containers do not update themselves: pull the new image instead.

[Back to Help](https://emule-qt.org/help/)

---

Part of eMule Qt. Site index for agents: https://emule-qt.org/llms.txt