Migrate to a new operating system

This is an example walkthrough for migrating an OMERO.server to a new operating system.

Basic steps

  1. Choose a platform. If your current installation platform does not match one of the recommended platforms, you may want to choose a new platform as your migration target. See Choosing a platform below.

  2. If you chhose to Install OMERO.server and OMERO.web separately (optionally, you can install both on a single device): It will be preferrable to choose the same platform type for both installations.

  3. Once both have been installed, perform an OMERO.server Backup and restore procedure.

Choosing a platform

The two recommended platforms are RHEL/RockyLinux 9 and Ubuntu 22.04.


The installation walkthroughs provided in the documentation covers a minimum installation only. For this, check the main server and web installation pages.

However, more advanced installation mechanisms are available if you are interested and have familiarity with the given mechanism:

  • Ansible roles are available for most installation steps. The primary roles, omero-server and omero-web allow to install respectively the OMERO.server and OMERO.web.

  • Docker images are also available. We offer production quality images of both omero-server and omero-web.

Please get in touch at https://forum.image.sc/tag/omero if you have any questions.

Backup and restore

Mininally, you will need to back up and restore the binary repository and the database.


  • Perform the backups following the backup instructions.

  • When ready, copy them to the new operating system:

    rsync -ra --progress db.dump NEW_OPERATING_SYSTEM:/tmp
    rsync -ra --progress OMERO_BINARY_BACKUP NEW_OPERATING_SYSTEM:/tmp

On the new operating system, stop the OMERO.server.

Restore the binary

  • Remove all the directories under /OMERO e.g. sudo rm -rf /OMERO/*.

  • Move the backup diretory containing the omero.config, /tmp/OMERO_BINARY_BACKUP/backup, out of /tmp/OMERO_BINARY_BACKUP

  • Change ownership and group of the directories under OMERO_BINARY_BACKUP:

    sudo chown -R omero-server /tmp/OMERO_BINARY_BACKUP/
  • As the omero-server user, move all the backup directories under /tmp/OMERO_BINARY_BACKUP to /OMERO, for example:

    sudo -u omero-server -s
    mv /tmp/OMERO_BINARY_BACKUP/ManagedRepository /OMERO/ManagedRepository

Restore the database

Restore the OMERO.server configuration

  • Restore the backup configuration:

    omero config load /tmp/OMERO_BINARY_BACKUP/backup/omero.config

You should then follow the Configuration steps of OMERO.server installation to adjust your configuration as/if necessary.

Virtual environments update

When installating the OMERO.server on the new operating system, a virtual environment /opt/omero/server/venv3 is created. If you have installated some specific packages in the virtual environment on the previous operating system, the packages will need to be re-installed in virtual environment on the new operating system.

The same is true for the OMERO.web virtual environment.


If you have added or modified scripts under lib/scripts on the previous operating system, you will need to back up your modifications and re-implement the modfications under lib/scripts on the new operating system, See Merge script changes


See Server certificate

Restart your server

  • Following a successful migration upgrade, you can start the server.

    $ omero admin start
  • If anything goes wrong, please send the output of omero admin diagnostics to the forum.

Reference OMERO.server upgrade, OMERO.server backup and restore.