Upgrade via built-in updater

The built-in updater automates many of the steps of upgrading a Nextcloud installation. It is useful for installations that do not have root access, such as shared hosting, for installations with a smaller number of users and data, and it automates updating :doc:`manual installations <../installation/source_installation>`.

What does the updater do?

The built-in updater performs these operations:

Check for expected files: checks if only the expected files of a Nextcloud installation are present, because it turned out that some files that were left in the Nextcloud directory caused side effects that risked the update procedure.
Check for write permissions: checks if all files that need to be writable during the update procedure are actually writable.
Enable maintenance mode: enables the maintenance mode so that no other actions are executed while running the update of the code.
Create backup: creates a backup of the existing code base in /updater-INSTANCEID/backups/nextcloud-CURRENTVERSION/ inside of the data directory (this does not contain the /data directory nor the database).
Downloading: downloads the code in the version it should update to. This is also shown in the web UI before the update is started. This archive is downloaded to /updater-INSTANCEID/downloads/.
Extracting: extracts the archive to the same folder.
Replace entry points: replaces all Nextcloud entry points with dummy files so that when those files are replaced all clients still get the proper maintenance mode response. Examples for those endpoints are index.php, remote.php or ocs/v1.php.
Delete old files: deletes all files except the above mentioned entry points, the data and config dir as well as non-shipped apps and themes. (And the updater itself of course)
Move new files in place: moves the files from the extracted archive in place.
Keep maintenance mode active?: asks you if the maintenance mode should be kept active. This allows the admin to use the web based updater but run the actual migration steps (occ upgrade) on the command line. If the maintenance mode is kept active command line access is required. To use the web based upgrade page disable the maintenance mode and click the link to get to the upgrade page. (This step is only available in the web based updater.)
Done the update of the code is done and you either need to go to the linked page or to the command line to finish the upgrade by executing the migration steps.

Using the command line based updater

You should see a notification at the top of any Nextcloud page when there is a new update available. Go to the admin settings page and scroll to the section "Version". This section has a button to open the updater. This section as well as the update notification is only available if the update notification app is enabled in the apps management.

Nextcloud admin settings Version section showing an update available notification

Instead of clicking that button you can now invoke the command line based updater by going into the updater/ directory in the Nextcloud directory and executing the updater.phar as the web server user. (i.e. sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar)

Terminal showing Nextcloud command line updater starting and displaying update information

Verify the information that is shown and enter "Y" to start the update.

Terminal showing Nextcloud command line updater executing update steps

Terminal showing Nextcloud command line updater with a failed step and error feedback

In case an error happens or the check failed the updater stops processing and gives feedback. You can now try to solve the problem and re-run the updater command. This will continue the update and re-run the failed step. It will not re-run the previous succeeded steps.

Terminal showing Nextcloud command line updater ready to continue after resolving an error

Once all steps are executed the updater will ask you a final question: "Should the "occ upgrade" command be executed?". This allows you to directly execute the command line based upgrade procedure (occ upgrade). If you select "No" then it will finish with Please now execute "./occ upgrade" to finish the upgrade..

Terminal showing Nextcloud command line updater asking whether to run the occ upgrade command

Once the occ upgrade is done you get asked if the maintenance mode should be kept active.

Terminal showing Nextcloud command line updater asking whether to keep maintenance mode active

Batch mode for command line based updater

It is possible to run the command line based updater in a non-interactive mode. The updater then doesn't ask any interactive questions. It is assumed that if an update is available it should be installed and the occ upgrade command is executed as well. After finishing the maintenance mode will be turned off except an error occurred during the occ upgrade or the replacement of the code.

To execute this, run the command with the --no-interaction option. (i.e. sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar --no-interaction)

Terminal showing Nextcloud command line updater running in non-interactive batch mode

Using a custom download URL

The --url option lets you override the archive the updater downloads. Common use cases:

Pinning a specific version — install an exact patch release rather than whatever the update check resolves to.
Internal mirrors — serve the archive from a company mirror or proxy.
Offline / air-gapped environments — stage the archive locally and supply it via a file:// URL.

Point the updater at any HTTP/HTTPS URL:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url https://download.nextcloud.com/server/releases/nextcloud-33.0.0.zip

For a locally staged archive, use a file:// URL:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip

Signature verification

When --url is used the updater cannot look up the official signature automatically. You have two options:

Provide the signature — pass the base64-encoded signature with --signature. You can get the signature from https://nextcloud.com/changelog/ or from the same mirror that hosts the archive:
```
sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --signature "BASE64_SIGNATURE_HERE"
```
Skip verification — pass --no-verify to disable integrity checking entirely. Only do this if you fully trust the source and transfer channel, or if you have already verified the archive yourself (e.g. by checking the SHA-512 checksum):
```
sha512sum -c nextcloud-33.0.0.zip.sha512
```
Then run the updater without signature checking:
```
sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --no-verify
```
Warning

--no-verify removes the integrity check that protects against corrupted or tampered archives. Always verify the archive through an independent channel before using this option.

These options can be combined with --no-interaction for fully automated runs:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --signature "BASE64_SIGNATURE_HERE" \
    --no-interaction

Using the web based updater

The web based updater performs the same steps and checks as the command line based updater.

Using the built-in updater to update your Nextcloud installation is just a few steps:

You should see a notification at the top of any Nextcloud page when there is a new update available. Go to the admin settings page and scroll to the section "Version". This section has a button to open the updater. This section as well as the update notification is only available if the update notification app is enabled in the apps management.

Click the button "Open updater".

Verify the information that is shown and click the button "Start update" to start the update.

In case an error happens or the check failed the updater stops processing and gives feedback. You can now try to solve the problem and click the "Retry update" button. This will continue the update and re-run the failed step. It will not re-run the previous succeeded steps.

In case you close the updater, before it finished you can just open the updater page again and proceed at the last succeeded step. Closing the web page will still execute the running step but will not continue with the next one, because this is triggered by the open updater page.

Once all steps are executed the updater will ask you a final question: "Keep maintenance mode active?". This allows you to use either the web based upgrade page or the command line based upgrade procedure (occ upgrade). Command line access is required if the maintenance mode is kept active.

Done. You now can continue either to the web based upgrade page or run occ upgrade. The two examples "Web based upgrade" and "Command line based upgrade" shows how the screens then look like.

Web based upgrade

This is how the web based update would continue:

Nextcloud web updater showing option to disable maintenance mode after upgrade

Nextcloud upgrade page displayed after the web updater completes

Command line based upgrade

This is how the command line based update would continue:

Nextcloud command line updater asking whether to keep maintenance mode active

$ sudo -u www-data php ./occ upgrade
Nextcloud or one of the apps require upgrade - only a limited number of commands are available
You may use your browser or the occ upgrade command to do the upgrade
Set log level to debug
Updating database schema
Updated database
Updating <files_pdfviewer> ...
Updated <files_pdfviewer> to 1.1.1
Updating <gallery> ...
Updated <gallery> to 17.0.0
Updating <activity> ...
Updated <activity> to 2.5.2
Updating <comments> ...
Updated <comments> to 1.2.0
Updating <theming> ...
Updated <theming> to 1.3.0
Starting code integrity check...
Finished code integrity check
Update successful
Maintenance mode is kept active
Reset log level

Troubleshooting

The built-in updater logs all of its actions to a dedicated log file called updater.log located in your configured datadirectory (e.g. /var/www/html/data/updater.log). This file can be helpful in isolating where things are failing. It will also be needed if you reach out for assistance on the community help forum (https://help.nextcloud.com).
If you are having problems using the Updater in web-mode, you should try using command-line mode (if it's an option in your environment). Command-line avoids issues with web server timeouts, which can be problematic since sometimes the Updater can take a long time to complete certain steps.
If the problem seems to be during the backup step, you can try disabling the backups the updater automatically creates of the installation files. Keep in mind these backups do not include your data (which you are already hopefully doing). The backup step can only be disabled while in command-line mode. Append the option --no-backup to the updater.phar command.
If you accidentally say no when the command-line mode of the updater asks if you'd like to run occ upgrade, you can safely execute occ upgrade manually or simply visit the URL of your instance to complete the database migrations and app upgrade phase.
Reach out to the community help forum for assistance (https://help.nextcloud.com)