Tame Nextcloud Preview CPU Spikes with a Scheduled Queue

If your Nextcloud server’s CPU spikes while previews are being created, the workload is often arriving in a burst: users open image-heavy folders, a large library is being indexed, or a preview job is trying to generate more sizes than people need. Install Nextcloud’s Preview Generator app, let it process new and changed files on a controlled schedule, and trim unnecessary preview sizes. This moves work out of busy browsing sessions; it does not make image conversion free or eliminate the initial catch-up workload.

These steps follow the Preview Generator README and Nextcloud 35 documentation checked October 10, 2026. Confirm compatibility for your release in the Nextcloud App Store. The README lists encrypted files as unsupported.

Why does preview generation drive CPU usage?

Nextcloud creates thumbnails as users request them unless a preview already exists. Image decoding, resizing, and conversion—especially for large originals or several target dimensions—can consume CPU and memory. A burst of requests makes this work visible at the same time as interactive use.

Preview Generator queues new or modified files for background processing. Existing previews are cheaper to serve, but missing previews still use Nextcloud’s on-demand path. The app shifts some work to quieter periods; it cannot reduce total processing or fix another bottleneck such as video conversion or slow storage.

Set up a controlled preview queue

1. Check the background-job mode and app compatibility

In Administration settings, inspect Background jobs. Preview Generator’s built-in job requires Cron mode; its README says AJAX and Webcron are unsupported for this long-running work. Nextcloud recommends system cron. Confirm the admin page reports Cron.

Install Preview Generator from the Apps screen, or, where your deployment uses OCC and permits app installation, run these commands from the Nextcloud installation directory. On Debian or Ubuntu, the web-server account is commonly www-data; use the actual HTTP user and PHP CLI version for your host:

sudo -u www-data php /var/www/nextcloud/occ app:install previewgenerator
sudo -u www-data php /var/www/nextcloud/occ app:enable previewgenerator

If it is already installed, skip the first command. Check status and available commands:

sudo -u www-data php /var/www/nextcloud/occ app:list
sudo -u www-data php /var/www/nextcloud/occ list preview

Run OCC as the HTTP user so file ownership stays consistent. Paths and users vary by deployment. See Nextcloud’s OCC documentation.

2. Reduce preview variants before starting a large generation run

Preview Generator can create square thumbnails and aspect-ratio previews at configured sizes. Its README says sizes must be powers of four, and an empty value skips that preview category. A restrained starting profile for a server struggling with load is shown below. It retains small square tiles and two aspect-ratio sizes, while skipping separate width-only and height-only variants:

sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="64 256" previewgenerator squareSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="256 1024" previewgenerator fillWidthHeightSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="" previewgenerator widthSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="" previewgenerator heightSizes

This lower-load profile is not universal: apps may need larger previews or other shapes. If thumbnails are missing or soft, identify the required view and add only its size. Larger dimensions increase processing and cache use. The README’s recommended minimum set for Files, Photos, and Activity uses a larger 4096-pixel size; assess that trade-off on your hardware. See the official Preview Generator README; it uses a larger 4096-pixel aspect-ratio size, so assess that trade-off on your hardware.

The preview_max_x and preview_max_y settings in config/config.php impose an overall pixel ceiling. Back up the file before editing and keep it compatible with chosen app sizes. Disabling previews removes thumbnails across apps.

3. Schedule the app’s pre-generation command without duplicating its worker

For a small server, the built-in queue worker can be sufficient once Cron mode is active. Its default job is limited to a maximum of five minutes per execution, and the app provides queue statistics for monitoring. If you need a predictable off-peak window, use the dedicated OCC command in system cron instead. When using that custom schedule, disable the app’s default queue job so both mechanisms do not compete:

sudo -u www-data php /var/www/nextcloud/occ config:app:set --value=true --type=boolean previewgenerator job_disabled

Then edit the crontab for the web-server user (sudo crontab -u www-data -e) and add an example schedule such as:

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

Ten minutes is only an example. Choose a cadence and window for your traffic and capacity; confirm your PHP and OCC paths. Do not schedule the command elsewhere too. Keep Nextcloud’s regular cron.php job, which runs other background tasks. See the Nextcloud background jobs guide documents the system cron setup.

4. Avoid an uncontrolled first-time catch-up run

The README suggests preview:generate-all after installation to cover existing files. On a large library, this catch-up run can cause a major CPU spike. Avoid many workers on a busy server. Start with one user or path during a quiet window and monitor CPU, memory, disk throughput, and free space. The command supports user IDs, paths, and worker count; begin with one worker. If needed, split the scan across windows.

Verify that load is becoming predictable

After the command runs, check the queue:

sudo -u www-data php /var/www/nextcloud/occ preview:queue-stats

Queue statistics include stale previews. A declining backlog and CPU peaks that end with scheduled work indicate the queue is progressing. Open a representative folder to confirm thumbnails, then observe normal browsing. Compare CPU at similar traffic levels; it will not reach zero.

If the queue does not shrink, inspect cron logs and run preview:pre-generate -vv in a controlled window to see processed files. If CPU stays high after the queue clears, investigate other PHP workers, jobs, or media services. If previews use too much disk, remove unused sizes or lower dimensions. Verify that the remaining previews support the views users need.

Official references

• Preview Generator README and OCC commands
• Nextcloud background jobs and system cron
• Nextcloud preview configuration
• Preview Generator compatibility and releases