How to Update Nextcloud: 3 Methods, One-Version Rule

Nextcloud updates require a specific process to avoid database corruption and lost apps. The three methods are: the web-based updater for small setups (under 500 users), the command-line tool for large instances, and Docker containers for containerized deployments. The critical rule: always update one major version at a time. Skip a version and your database schema breaks, leaving you stuck in maintenance mode. Back up your database and data directory before touching anything. This guide walks you through each method, the version rule, recovery if things fail, and how to manage third-party apps through the process.

Before You Update: Essential Backup and Compatibility Checks

Nextcloud's built-in updater does not back up your system first. You must do this manually. A failed update without backups means lost files, lost configurations, and potential data corruption. Take 15 minutes now to save weeks of recovery work later.

Start with your database. If Nextcloud uses MySQL or MariaDB, SSH into your server and run:

mysqldump -u nextcloud_user -p nextcloud_database > nextcloud-backup-$(date +%Y%m%d).sql

Replace nextcloud_user and nextcloud_database with your actual credentials. If you use PostgreSQL, the command is:

pg_dump -U nextcloud_user nextcloud_database > nextcloud-backup-$(date +%Y%m%d).sql

Next, back up your configuration and data directories. Configuration lives in /var/www/nextcloud/config. Data lives in /var/www/nextcloud/data (or wherever you mounted it). Use rsync or tar:

sudo tar -czf nextcloud-config-backup-$(date +%Y%m%d).tar.gz /var/www/nextcloud/config
sudo tar -czf nextcloud-data-backup-$(date +%Y%m%d).tar.gz /var/www/nextcloud/data

Before updating, verify your PHP version. Nextcloud requires specific PHP versions for each major release. Check which version you have:

php -v

Nextcloud 34 and 35 require PHP 8.1 or higher. Older versions need PHP 7.4 or 8.0. If your PHP version is too old, upgrade it first before attempting the Nextcloud update.

Finally, take inventory of your third-party apps. Log into Nextcloud as admin, go to Settings > Apps, and note which apps you have enabled. During the update, Nextcloud will automatically disable all third-party apps. You will re-enable them after the update completes. If an app is incompatible with the new version, it will stay disabled until the app maintainer updates it.

Understanding the One-Major-Version-at-a-Time Rule

Nextcloud enforces sequential updates for a reason: database schema changes. Each major version modifies your database structure. Skipping versions leaves your database in an inconsistent state. Your instance gets stuck in maintenance mode, and occ commands may fail.

Here is the rule in practice. If you run Nextcloud 26 and want to update to 29, you must go:

26 27 28 29

You cannot jump from 26 to 29. The Nextcloud updater will refuse the jump and show an error.

Minor versions (26.0.1, 26.0.2) can be skipped. You can jump from 26.0.1 directly to 26.0.10. But major versions must be sequential.

Why? Nextcloud modifies database tables, adds columns, and removes deprecated fields between major versions. If you skip a version, those intermediate schema changes never run. The next version's migration script expects the previous version's schema to exist. It fails, rolls back, and leaves Nextcloud in maintenance mode.

A Reddit user once jumped from version 26 to 32, skipping four versions. The update failed halfway through. Their Nextcloud was stuck in maintenance mode for three days while they manually restored from backups. This is a real scenario: do not skip versions.

Update Method 1: Web-Based Updater (GUI)

The web updater is the easiest method if you have a small instance (under 500 users) with a fast connection. It shows progress in your browser and handles maintenance mode automatically.

First, place Nextcloud in maintenance mode. Go to Settings > Administration > Overview. Scroll to the Nextcloud updates section. Click "Enable maintenance mode." You will see a message: "Nextcloud is in maintenance mode. Only administrators can access the web interface."

Next, check for updates. Stay on the same page. If an update is available, you will see a blue "Update" button. Click it.

The updater will download the new version (100+ MB), verify the files, and run database migrations. On a 100 MB connection and a 500-user database, this takes 2 to 5 minutes. Do not close your browser tab.

Common issues: The web updater times out on large instances or slow connections. If your update hangs for more than 10 minutes, do not retry. Use the command-line method instead (see below). A stuck web update leaves Nextcloud in maintenance mode. You must disable maintenance mode manually using SSH before trying again.

Once the update finishes, Nextcloud disables maintenance mode automatically. Reload the admin panel and verify the new version number appears in Settings > Administration > Overview.

Update Method 2: Command-Line (occ) -- Recommended for Large Instances

The command-line tool (occ) is the most reliable method. It does not time out, shows clear error messages, and works on instances with 1000+ users or terabytes of data.

SSH into your server and navigate to the Nextcloud root:

cd /var/www/nextcloud

Run the upgrade command as the web server user (usually www-data):

sudo -u www-data php occ upgrade

The tool will:

1. Check PHP version compatibility
2. Verify database connection
3. Back up the current database (important: the occ tool does auto-backup before running migrations)
4. Run database schema changes
5. Re-enable apps
6. Return a success message

On a 5 GB database with 2000 users, this takes 10 to 20 minutes. You will see progress messages in the terminal.

After the upgrade completes, run the missing indices check. Database performance degrades if indices are missing:

sudo -u www-data php occ db:add-missing-indices

This is fast (usually under 1 minute) and improves query speed.

If anything goes wrong, the occ tool will print an error and stop. You can then restore from your database backup (see Recovery section below).

Update Method 3: Docker and Docker AIO

If you run Nextcloud in Docker Compose, update by pulling the latest image:

cd /path/to/docker-compose.yml
docker compose pull
docker compose up -d

The pull command fetches the latest version of the Nextcloud image. The up -d command stops the old container and starts a new one with the latest version. Migrations run automatically inside the container.

If you use Docker AIO (All-in-One), the Nextcloud container has a built-in update mechanism. You do not need to run occ commands. The container handles upgrades internally when you pull and restart.

To prevent accidental major version jumps in Docker, pin the version in your docker-compose.yml:

services:
  nextcloud:
    image: nextcloud:34-apache

This pins Nextcloud 34. When you pull, Docker will not fetch version 35 automatically. You must manually change the tag to 34-apache when you are ready.

If you omit a version tag and use image: nextcloud:latest, Docker will pull whatever the latest version is, even if you skip a major version. This breaks the one-major-version rule. Always pin your version.

After updating, check the Docker logs to confirm the update succeeded:

docker compose logs nextcloud | tail -20

Look for "Nextcloud is ready" or similar success messages. If you see database errors, restore from your backup and try again.

Managing Apps During Updates

During a Nextcloud update, all third-party apps automatically disable. This is a safety feature. Nextcloud checks each app for compatibility with the new version. If an app was written for version 26 and you are updating to 27, the app may not work. Disabling it prevents errors and crashes.

After the update finishes, go to Settings > Apps. You will see a list of disabled apps with a blue "Enable" button next to each. Only enable apps that are compatible with the new version.

Before enabling an app, check Nextcloud's official app directory to see if the app maintainer has released a version for your new Nextcloud release. If the app directory shows no update for the new version, the app may break. Contact the app maintainer or find an alternative.

Some apps take days or weeks to update after a new Nextcloud version ships. If you need that app immediately, do not upgrade Nextcloud yet. Wait for the app update first.

If an app is critical and the maintainer has not updated it, you can try enabling it anyway (at your own risk). If it breaks your Nextcloud instance, disable it immediately:

sudo -u www-data php occ app:disable problematic-app

Recovery: What to Do If an Update Fails

Updates fail for three main reasons: PHP incompatibility, database locks, and corrupted files. Here is how to recover from each.

Nextcloud stuck in maintenance mode: Your update started but did not finish. Your Nextcloud is inaccessible to regular users. Disable maintenance mode immediately:

sudo -u www-data php occ maintenance:mode --off

This allows users to log in again. Users can access their files while you troubleshoot the update failure.

Corrupted database after failed update: Restore your database backup:

mysql -u nextcloud_user -p nextcloud_database < nextcloud-backup-20261015.sql

Then restore your config and data directories from your tar backups:

sudo rm -rf /var/www/nextcloud/config
sudo tar -xzf nextcloud-config-backup-20261015.tar.gz
sudo rm -rf /var/www/nextcloud/data
sudo tar -xzf nextcloud-data-backup-20261015.tar.gz

Finally, run the repair command to fix any inconsistencies:

sudo -u www-data php occ maintenance:repair

Missing database indices after update: The update ran but did not finish the final steps. Run the missing indices check:

sudo -u www-data php occ db:add-missing-indices

If this command fails with a "database locked" error, another process is holding a lock. Wait 5 minutes and try again. If the lock persists, restart the web server:

sudo systemctl restart php-fpm
sudo systemctl restart nginx

(Or apache2 if you use Apache instead of nginx.)

Rolling back to the previous version: Nextcloud does not support downgrading. If you need to go back, you must restore your entire backup (database, config, data) from before the update. This is why backups are non-negotiable.

Frequently Asked Questions

How do I update the Nextcloud Docker image? Use docker compose pull && docker compose up -d to fetch the latest image and restart the container. Migrations run automatically inside the container.

Can I skip a major version when updating Nextcloud? No. Nextcloud enforces sequential updates. You must update 26 27 28 29, never 26 29. Skipping versions breaks the database schema and leaves Nextcloud stuck in maintenance mode.

How long does a Nextcloud update take? Small instances (under 500 users, under 100 GB data): 2 to 5 minutes via web updater, under 10 minutes via CLI. Large instances (1000+ users, terabytes of data): 15 to 30 minutes via CLI. Docker updates are typically under 5 minutes because the migrations run inside the container.

What should I do if the update fails? First, disable maintenance mode: sudo -u www-data php occ maintenance:mode --off. Then, check the logs. If the database is corrupted, restore from your backup. If database indices are missing, run sudo -u www-data php occ db:add-missing-indices.

Do I need to stop Nextcloud before updating? The web updater and occ tool stop background jobs automatically. If you use Docker, the container restarts. For manual CLI updates, stop your web server: sudo systemctl stop nginx (or apache2), then start it again after the update.

Can I update Nextcloud during business hours? No. Updates require maintenance mode. Your users cannot access Nextcloud while maintenance mode is on. Always update outside business hours or on weekends. Set a specific window and notify users in advance.

How do I check which version of Nextcloud I have? Log in as admin and go to Settings > Administration > Overview. The version number appears at the top. You can also check via CLI: sudo -u www-data php occ -V.

The Bottom Line

Nextcloud updates are safe if you follow the process: backup first, respect the one-major-version rule, use the CLI method for large instances, and always have a recovery plan. Reddit's update complaint threads are full of users who skipped backups or tried to jump versions. You are smarter than that.

If managing self-hosted Nextcloud updates feels risky or you lack the technical resources to handle failures, Opsily's managed Nextcloud hosting removes the burden entirely. We handle all updates, backups, and recovery. Your team accesses Nextcloud without worrying about maintenance windows or version rules.