How to upgrade
There are three ways to upgrade your Nextcloud server:
With the Updater.
Manually upgrading with the Nextcloud
.tar
archive from our Download page.Upgrading via the snap packages.
Manually upgrading is also an option for users on shared hosting; download and unpack the Nextcloud tarball to your PC. Delete your existing Nextcloud files, except
data/
andconfig/
files, on your hosting account. Then transfer the new Nextcloud files to your hosting account, again preserving your existingdata/
andconfig/
files.
When an update is available for your Nextcloud server, you will see a notification at the top of your Nextcloud Web interface. When you click the notification it brings you here, to this page.
It is best to keep your Nextcloud server upgraded regularly, and to install all point releases and major releases. Major releases are 18, 19 or 20. Point releases are intermediate releases for each major release. For example 18.0.4 and 19.0.2 are point releases.
- Nextcloud must be upgraded step by step:
Before you can upgrade to the next major release, Nextcloud upgrades to the latest point release.
Then run the upgrade again to upgrade to the next major release’s latest point release.
You cannot skip major releases. Please re-run the upgrade until you have reached the highest available (or applicable) release.
Example: 18.0.5 -> 18.0.11 -> 19.0.5 -> 20.0.2
Upgrading is disruptive. Your Nextcloud server will be put into maintenance mode, so your users will be locked out until the upgrade is completed. Large installations may take several hours to complete the upgrade. Nevertheless usual upgrade times even for bigger installations are in the range of a few minutes.
Warning
Downgrading is not supported and risks corrupting your data! If you want to revert to an older Nextcloud version, make a new, fresh installation and then restore your data from backup. Before doing this, file a support ticket (if you have paid support) or ask for help in the Nextcloud forums to see if your issue can be resolved without downgrading.
Update notifications
Nextcloud has an update notification app, that informs the administrator about the availability of an update. Then you decide which update method to use.
From there the web based updater can be used to fetch this new code. There is also an CLI based updater available, that does exactly the same as the web based updater but on the command line.
Prerequisites
You should always maintain regular backups and make a fresh backup before every upgrade.
Then review third-party apps, if you have any, for compatibility with the new Nextcloud release. Any apps that are not developed by Nextcloud show a 3rd party designation. Install unsupported apps at your own risk. Then, before the upgrade, all 3rd party apps must be disabled. After the upgrade is complete you may re-enable them.
Maintenance mode
You can put your Nextcloud server into maintenance mode before performing
upgrades, or for performing troubleshooting or maintenance. Please see
Using the occ command to learn how to put your server into
the maintenance mode (maintenance:mode
) or execute repair commands
(maintenance:repair
) with the occ
command.
The build-in Updater does this for you before replacing the existing Nextcloud code with the code of the new Nextcloud version.
maintenance:mode
locks the sessions of logged-in users and prevents new
logins. This is the mode to use for upgrades. You must run occ
as the HTTP
user, like this example on Ubuntu Linux:
$ sudo -u www-data php occ maintenance:mode --on
You may also put your server into this mode by editing config/config.php
.
Change "maintenance" => false
to "maintenance" => true
:
<?php
"maintenance" => true,
Then change it back to false
when you are finished.
Manual steps during upgrade
Some operation can be quite time consuming. Therefore we decided not to add them to the normal upgrade process. We recommend to run them manually after the upgrade was completed. Below you find a list of this commands.
Long running migration steps
From time to time we do some changes to the database layout that take a lot of time, but can be executed while Nextcloud stays online. Thus we moved them into a separate command that an administrator can execute on the CLI without the need to lock the instance into maintenance mode (at least for some of them). The instance will also work without those changes applied, but performance is improved significantly by them. There is also always an hint in the setup checks of the admin settings web interface.
Those include for example:
$ sudo -u www-data php occ db:add-missing-columns
$ sudo -u www-data php occ db:add-missing-indices