Resources
🤖 For AI agents: The complete documentation index is available at /docs/llms.txt. A markdown version of this page is available at /docs/get-started/download-and-install/upgrade.md.

Upgrade FusionAuth

Edit on GitHub
View Markdown

This page explains how to upgrade FusionAuth to a newer version.

To upgrade an instance of FusionAuth configured with a container management tool such as Docker Desktop, OrbStack, or Podman:

  1. Stop the instance:

    $ docker compose down

  2. Modify the docker-compose.yml file to point to the version of FusionAuth you want. The following command will upgrade you to the latest version:

    $ docker pull fusionauth/fusionauth-app:latest

    For a full list of available tags, see fusionauth-app on Docker Hub.

  3. Start your instance:

    $ docker compose up -d

  4. Open the System -> About page in the Admin UI to check your instance's version of FusionAuth.

  1. First, shut down FusionAuth:

    $ <FUSIONAUTH_HOME>/bin/shutdown.sh

  2. Then, from the parent directory of FUSIONAUTH_HOME, run the FastPath install command. For example, if FUSIONAUTH_HOME is /home/example/dev/fusionauth, run the command from /home/example/dev:

    $ curl -fsSL https://raw.githubusercontent.com/FusionAuth/fusionauth-install/master/install.sh | bash -s && \

  3. Start FusionAuth:

    $ <FUSIONAUTH_HOME>/bin/startup.sh

If you initially installed FusionAuth using Homebrew, you can also use Homebrew to upgrade to the latest version of FusionAuth.

To upgrade FusionAuth using brew, follow the steps below:

  1. Stop fusionauth-app using Homebrew services:

    $ brew services stop fusionauth-app

  2. Upgrade the version of fusionauth-app:

    $ brew upgrade fusionauth-app

  3. Start fusionauth-app with Homebrew services:

    $ brew services start fusionauth-app

  1. Terminate the running FusionAuth App and Search services:

    <FUSIONAUTH_HOME>\bin\shutdown.ps1

  2. Then, from the parent directory of FUSIONAUTH_HOME, run the FastPath install command. For example, if FUSIONAUTH_HOME is \Users\example\dev\fusionauth, run this command from \Users\example\dev:

    Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/FusionAuth/fusionauth-install/main/install.ps1 | iex

  3. Start FusionAuth:

    <FUSIONAUTH_HOME>\bin\startup.ps1

Migrations#

If there were database migrations required, what happens on an upgrade depends on two settings: the runtime mode and the silent mode.

If silent mode is set to true, FusionAuth will automatically migrate your database to the latest schema version.

If silent mode is false and the runtime mode is set to development, Maintenance mode will appear when you access any URL hosted by FusionAuth. Follow the prompts to complete the migrations.

In all other cases the migrations will not be applied, and you'll have to perform them yourself. If you want to manage your own database upgrades, performing the SQL migrations out of band with another tool or process is a good option.

When Are Database Migrations Applied

Runtime ModeSilent ModeMigration Behavior
developmenttrueMigration applied automatically
developmentfalseMaintenance mode UI displayed, user prompted to run migrations
productiontrueMigration applied automatically
productionfalseMigration never applied by FusionAuth, must be applied out of band

See the configuration reference or the silent mode guide for more information. To apply the database migrations out of band see the database upgrade documentation.

Docker latest Tag#

The Docker Compose file references the latest tag, but that tag is not dynamic. It is only the latest at a point in time. To get the most recently released image, you have a couple of options:

  • Pull the latest image with this command: docker pull fusionauth/fusionauth-app:latest or docker compose pull and recreate your deployment with docker compose up -d which will recreate every container where a new image is available.
  • Edit the Docker Compose file to specify a specific version. This is a good idea for a production deployment. Run docker compose pull you can only pull the specified image, or just run docker compose up -d which will pull the image and recreate the container at the same time.
  • Remove all images with docker rmi <IMAGE ID> selected from the list of IMAGE IDs which you can show with docker images. This requires that the image isn't used and therefore may prompt you to remove containers using it. Since FusionAuth stores all state in the database, and for docker you use volumes to persist data, you can safely remove the containers. After that you can use docker compose pull, docker compose build and docker compose up -d accordingly to get images specified the in the docker-compose.yml.

Use docker image prune to remove all unused images after upgrading.