# Upgrading

**URL:** https://heroiclabs.com/docs/nakama/getting-started/upgrade/
**Summary:** How to upgrade your Nakama server to a new version.
**Keywords:** upgrading nakama, upgrade, docker, upgrade nakama
**Categories:** nakama, upgrade, getting-started

---


# Upgrade Nakama

When upgrading to a new version of Nakama, you need to do three things before you run the newer version:

- Check the [Release Notes](../release-notes/), in case that version has specific upgrade requirements.
- Migrate your data to the format supported by the new version of Nakama.
- Ensure that the client version you’re running is compatible with the server deployed.

## Docker

As new versions of Nakama, or CockroachDB, become available you might want to upgrade. Docker makes upgrading easy, as all you need to do is pull down a new version of the container image. When upgrading to a new version of Nakama, the process in the `docker-compose.yml` performs a migration of your data to the new database schema automatically.

You can pull the most recent Nakama image and allow Docker Compose to perform the data migration.

```sh
docker-compose down # top and remove both the Nakama and CockroachDB containers
docker pull heroiclabs/nakama # download the latest Nakama image
docker-compose up # start the containers (both Nakama and CockroachDB) as fresh installs
```

And, similarly, here’s how to update the CockroachDB container:

```sh
docker pull cockroachdb/cockroach # download the latest CockroachDB image
```

If you'd like to explicitly run a database schema migration, issue the following command:

```sh
docker run heroiclabs/nakama migrate up
```

## Manual upgrade

You can upgrade one node or your whole cluster to the latest version of Nakama by following the instructions below.

For each node in the cluster:

Stop Nakama. If you are using `systemd` on a Linux setup, the command is:

```sh
sudo systemctl stop nakama
```

Back-up CockroachDB:

```sh
cockroach dump nakama > mydatabackup.sql --insecure
```

Download the [latest release](https://github.com/heroiclabs/nakama/releases/latest) and replace the `nakama` binary with the newer download.

Upgrade the database schema with the following command:

```sh
nakama migrate up
```

To downgrade Nakama you can follow the same procedure, but replace the migration command with the following:

```sh
nakama migrate down --limit 1
```

Start Nakama and verify that the upgraded version is running.

```sh
sudo systemctl start nakama
```