How to generate Nextcloud previews

Nextcloud previews are the thumbnails shown in Files, Photos, and other file views before a user opens the original file. On servers with many images or other supported previewable files, creating those derivatives ahead of demand reduces the delay users see the first time a folder is opened.

The Preview Generator app adds occ commands for initial and incremental preview creation. preview:generate-all walks existing files, while preview:pre-generate processes new or changed files recorded by the app after it has been enabled.

Run occ from the Nextcloud web root as the web-server user, and plan the first pass for a quiet maintenance window on large data sets. The app is intended for unencrypted file storage; generated previews can also increase disk use because Nextcloud stores derivatives under its app data.

1. Change to the Nextcloud web root.

   $ cd /var/www/nextcloud

   Use the directory that contains the occ file if the installation uses a different path.

   Related: How to run Nextcloud occ commands

2. Install the Preview Generator app.

   $ sudo -E -u www-data php occ app:install previewgenerator
   previewgenerator 5.14.0 installed
   previewgenerator enabled

   The Preview Generator app does not work with Nextcloud server-side encryption enabled.

   Related: How to install a Nextcloud app

3. Generate previews for the target folder.

   $ sudo -E -u www-data php occ preview:generate-all --path="/ada/files/Photos" -vv
   2026-06-28T23:17:37+00:00 Scanning folder /ada/files/Photos
   2026-06-28T23:17:37+00:00 Generating previews for /ada/files/Photos/project-cover.png

   Use --path="/username/files/folder" for a bounded first run. Omit --path to walk all users, or add one or more user IDs after the command to process selected accounts. If the files were copied directly into the data directory instead of uploaded through Nextcloud, scan them first.
   Related: How to scan files with Nextcloud occ

4. Open the web-server user's crontab.

   $ sudo crontab -u www-data -e

   The scheduled job must run as the same user that owns the Nextcloud web files, commonly www-data on Debian and Ubuntu.

   Related: How to configure Nextcloud background jobs with cron

5. Add a scheduled incremental preview job.

   */10 * * * * php /var/www/nextcloud/occ preview:pre-generate

   Ten minutes is a common interval for small and medium servers. Use the full PHP path if the server's CLI PHP differs from the web runtime.

6. Disable the app's built-in background job when using the dedicated cron entry.

   $ sudo -E -u www-data php occ config:app:set --value=true --type=boolean previewgenerator job_disabled
   Config value 'job_disabled' for app 'previewgenerator' is now set to '1', stored as boolean in fast cache

   The dedicated cron entry still runs preview:pre-generate. This setting prevents the app background job from duplicating the same queue processing.

7. Run the incremental preview command once from the shell.

   $ sudo -E -u www-data php occ preview:pre-generate -vv

   No output can mean the preview queue is already empty. With pending files, -vv prints the processed paths.

8. Check the preview queue statistics.

   $ sudo -E -u www-data php occ preview:queue-stats
   +-----------------------+-----------------+
   | Age                   | Queued previews |
   +-----------------------+-----------------+
   | Less than 10 minutes  | 0               |
   | Less than 30 minutes  | 0               |
   | Less than one hour    | 0               |
   | Less than three hours | 0               |
   | Less than a day       | 0               |
   | Less than a week      | 0               |
   | All                   | 0               |
   +-----------------------+-----------------+

   A zero queue after preview:pre-generate means there are no tracked previews waiting for the incremental run. Open the same folder in Files to confirm supported thumbnails appear without waiting for on-demand generation.