Setting Up Nextcloud Preview Generator (September 2026)

If your Nextcloud gallery crawls when you open a folder full of photos, the fix is usually the same: install the Nextcloud Preview Generator app, generate thumbnails ahead of time, and run a cron job (or systemd timer) to keep them fresh. I have been running self-hosted Nextcloud servers since 2018, and the preview generator is one of those apps that turns a sluggish photo library into something that scrolls like a native app. In this guide, I will walk you through the exact steps I use to set up the Nextcloud Preview Generator for fast photo thumbnails on a fresh server, including the config.php tweaks, cron syntax, systemd alternative, and the troubleshooting steps that solve the issues I see on forums most often.

Quick Answer: What Is Preview Generator and How Do I Set It Up?

The Nextcloud Preview Generator is an official Nextcloud app that pre-renders thumbnails and previews for all images, videos, and PDFs in your library. Instead of generating a thumbnail when a user opens a folder (which causes lag), the app listens for upload and edit events, queues the work, and runs occ preview:pre-generate on a schedule. To set it up: install the app from the Nextcloud App Store, add 'enable_previews' => true and an 'enabledPreviewProviders' list in config.php, run occ preview:generate-all once for existing files, then add a cron job every 10 minutes. Total setup time is about 15 minutes for a clean install.

Prerequisites Before You Start

Before you run any commands, confirm these four things on your server. I have wasted hours on this app because I skipped one of these and had to debug permissions later.

• PHP CLI binary path. Most Linux servers use /usr/bin/php, but Debian and Ubuntu Snap installs sometimes use /usr/bin/php8.3 or another versioned path. Run which php to check.
• Web server user. On Debian/Ubuntu this is www-data. On CentOS/RHEL it is apache. On unRAID it is usually nobody. The cron job must run as this user.
• Nextcloud occ location. This is your Nextcloud root directory, for example /var/www/nextcloud/occ. If you use Docker, you run it inside the container.
• System cron working. Run crontab -l as the web user to confirm cron is functional before adding the preview generator entry.

You also need FFmpeg and ImageMagick installed if you want video thumbnails. Most photo-only users can skip this, but I recommend installing both for a complete setup.

Step 1: Install the Preview Generator App

You have two options: install through the Nextcloud web interface (Apps section) or via the command line. I prefer the command line because it gives clearer feedback and works even when the web UI is broken.

From your Nextcloud root directory, run these commands as the web server user:

sudo -u www-data php occ app:install previewgenerator

If the app is already installed but disabled, enable it instead:

sudo -u www-data php occ app:enable previewgenerator

You should see previewgenerator enabled in the output. If you get a permission error, your sudoers config or file ownership needs fixing. The Nextcloud directory and all files inside must be owned by the web server user.

Step 2: Configure Preview Settings in config.php

This is the step most guides skip, and it is the one that makes the biggest difference for performance. Open your config.php file (usually at /var/www/nextcloud/config/config.php) and add the following to the $CONFIG array.

'enable_previews' => true,
'enabledPreviewProviders' => [
  'OCPreviewJPEG',
  'OCPreviewPNG',
  'OCPreviewGIF',
  'OCPreviewBMP',
  'OCPreviewXBitmap',
  'OCPreviewMP3',
  'OCPreviewTXT',
  'OCPreviewMarkDown',
  'OCPreviewHEIC',
  'OCPreviewMovie',
  'OCPreviewPDF',
  'OCPreviewSVG',
],
'preview_max_x' => 2048,
'preview_max_y' => 2048,
'preview_libreoffice_path' => '/usr/bin/libreoffice',
'preview_ffmpeg_path' => '/usr/bin/ffmpeg',

What each setting does: enable_previews turns on the preview system as a whole. enabledPreviewProviders is the list of file types that get previews; without this, only images get thumbnails. preview_max_x and preview_max_y set the upper size limit for generated previews. The FFmpeg and LibreOffice paths let the server generate video and document thumbnails.

For a photo-heavy library, you can drop the music and document providers from the list to save resources. I keep them all on because disk space is cheap compared to user complaints.

Step 3: Generate All Previews for Existing Files

Now you need to backfill thumbnails for everything already in your library. Without this step, only newly uploaded files after the cron starts will have previews. Run this command from your Nextcloud root:

sudo -u www-data php occ preview:generate-all

This can take hours on a large library. On my own server with about 80k photos and videos, it took roughly 6 hours on a 4-core machine. You can speed it up with parallel workers:

sudo -u www-data php occ preview:generate-all -n 4

The -n 4 flag tells Preview Generator to use 4 parallel workers. Set this to roughly the number of CPU cores you can spare. Going higher than your CPU count causes diminishing returns and can crash PHP with out-of-memory errors.

To target a specific folder instead of your entire library, use the -p flag:

sudo -u www-data php occ preview:generate-all -p "Photos/2024/Vacation"

This is useful when you add a new folder of thousands of photos and do not want to wait for the full scan.

Step 4: Set Up a Cron Job for Ongoing Generation

Open the crontab for the web server user:

sudo -u www-data crontab -e

Add this line to run previews every 10 minutes:

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

Use the full PHP path if /usr/bin/php is not in the cron PATH. Replace /var/www/nextcloud/occ with your actual Nextcloud root. Save and exit; cron will pick it up on the next minute.

Verify it ran by checking the Nextcloud log file at /var/www/nextcloud/data/nextcloud.log. You should see entries about preview generation shortly after the next 10-minute window. You can also run the command manually first to confirm it works:

sudo -u www-data php /var/www/nextcloud/occ preview:pre-generate

If you want to see what is in the queue, run occ preview:queue-stats. This prints the number of previews waiting, in progress, and total processed.

Step 5: Systemd Timer Alternative (Recommended)

I prefer systemd timers over cron for Nextcloud preview generation because timers give you better logging, dependency management, and the ability to run missed jobs after downtime. Cron has no concept of “catch up if I was asleep”, so a server outage means previews pile up without ever being generated.

Create a service file at /etc/systemd/system/nextcloud-preview.service:

[Unit]
Description=Nextcloud Preview Generator
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=www-data
ExecStart=/usr/bin/php /var/www/nextcloud/occ preview:pre-generate
Nice=19

Then create a timer file at /etc/systemd/system/nextcloud-preview.timer:

[Unit]
Description=Run Nextcloud Preview Generator every 10 minutes
Requires=nextcloud-preview.service

[Timer]
OnBootSec=2min
OnUnitActiveSec=10min
Persistent=true
Unit=nextcloud-preview.service

[Install]
WantedBy=timers.target

Enable and start the timer:

sudo systemctl daemon-reload
sudo systemctl enable nextcloud-preview.timer
sudo systemctl start nextcloud-preview.timer

Check the status with systemctl list-timers --all | grep nextcloud. The Persistent=true line is the key benefit: if your server was down at the scheduled run time, the timer fires immediately on boot to catch up.

Cron vs Systemd Timers: Which Should You Use?

Both work. Cron is simpler if you have never used systemd and just want a quick setup. Systemd timers are better for production servers that get rebooted or have variable uptime.

• Cron pros: universal, simple syntax, works in any environment.
• Cron cons: no missed-job recovery, harder to debug failures, no native logging.
• Systemd pros: catches up after downtime, integrates with journald logs, supports dependencies and resource limits.
• Systemd cons: Linux-only (no Windows), slightly more setup.

I run systemd timers on every server I manage. If you are on Windows or macOS for some reason, cron is not available, and you need a different approach (see Windows section below).

Preview Size Optimization: The Power of 4 Rule

Nextcloud can render multiple preview sizes for each file: square crops for gallery views, fixed-width images for the Files app, and full-resolution previews for the Photos app. Each size costs disk space but makes browsing faster. The default sizes are designed for mobile screens, so if you use Nextcloud on a desktop with a 4K monitor, you probably want larger previews.

The “power of 4” rule means using sizes like 64, 256, 1024, 4096 pixels. These line up with how JPEG compression works internally, which makes files slightly smaller and decoding faster. Non-power-of-4 sizes still work but waste a few percent of disk space.

To customize preview sizes, add this to config.php:

'squareSizes' => [32, 64, 128],
'widthSizes' => [256, 1024, 1920],
'heightSizes' => [256, 1024, 1080],
'coverWidthHeightSizes' => [128, 768, 2048],
'fillWidthHeightSizes' => [256, 1024],

The squareSizes array is for the gallery thumbnails (square crops). widthSizes controls the width-based previews shown in the Files app. coverWidthHeightSizes is for the Memories app cover photos. Each size you add roughly multiplies the storage used for previews by 4, so do not add sizes you do not need.

After changing preview sizes, regenerate everything:

sudo -u www-data php occ preview:cleanup
sudo -u www-data php occ preview:generate-all

The cleanup step removes the old previews at the wrong sizes; without it, you end up with duplicates.

Troubleshooting Common Issues

Allowed Memory Size Exhausted

The most common error when running preview:generate-all is PHP running out of memory. The default 128MB limit is too low for large image libraries. Increase it in your php.ini or pass it inline:

sudo -u www-data php -d memory_limit=1024M occ preview:generate-all

For long-running generation jobs, 1GB to 2GB is reasonable. Do not exceed your server’s total RAM.

Cron Job Not Running

If previews stop appearing for new uploads, check that cron is actually executing. First, confirm cron is running on the system (systemctl status cron or systemctl status crond). Then check the system mail for the web user; cron sends errors there. On modern systems without local mail, check /var/log/syslog or journalctl -u cron. Finally, add a temporary logging line to your cron entry:

*/10 * * * * php /var/www/nextcloud/occ preview:pre-generate >> /var/log/nextcloud-preview.log 2>&1

Then tail that log file to see what is happening.

Video Thumbnails Not Generating

If your photo previews work but videos stay blank, FFmpeg is either missing or in the wrong path. Verify the binary:

which ffmpeg
ffmpeg -version | head -1

If FFmpeg is not installed, install it on Debian/Ubuntu with sudo apt install ffmpeg. On CentOS, use sudo yum install epel-release && sudo yum install ffmpeg. On Docker, add ffmpeg to your Dockerfile or compose file. Then update the preview_ffmpeg_path setting in config.php to match the binary location.

Android or iOS App Thumbnails Slow

The official Nextcloud mobile apps do not use the Preview Generator directly. They pull thumbnails one at a time as you scroll, which feels slow on big libraries. To improve this, make sure preview_max_x and preview_max_y are set high enough (2048 is a good default). The mobile apps prefer larger previews to avoid blurriness on high-density phone screens.

For iOS specifically, force the app to refresh by pulling down on the folder view. The app caches thumbnails aggressively, and sometimes a manual refresh is the only fix.

New Uploads Missing Thumbnails Until Next Cron Run

This is normal behavior. The Preview Generator queues files when they are uploaded, but the actual generation only happens when the cron job runs. If your cron runs every 10 minutes, there can be up to a 10-minute delay. To reduce this, run the cron more frequently (every 5 minutes) or trigger the pre-generate command after uploads with a Nextcloud hook.

Windows and Docker Setup Notes

If you run Nextcloud on Windows, cron is not available. Use Windows Task Scheduler instead. Create a basic task that runs every 10 minutes, with the action set to:

C:phpphp.exe C:nextcloudocc preview:pre-generate

Adjust the paths to match your installation. The web server user concept does not apply on Windows; just run the command as the user that installed Nextcloud.

For Docker users, run the occ command inside your container:

docker exec --user www-data nextcloud php occ preview:generate-all

Replace nextcloud with your container name. Cron inside the container works the same as on bare metal; the official Nextcloud Docker image sets up cron automatically.

Resetting and Regenerating All Previews

If your previews look corrupted, are the wrong size, or you changed config.php and want a clean slate, run this sequence:

sudo -u www-data php occ preview:cleanup
sudo -u www-data php occ preview:generate-all -n 4

The cleanup step deletes all existing preview files. The generate-all step recreates them with your current configuration. This can take many hours on large libraries, so I usually run it in a screen or tmux session so the job survives SSH disconnects:

screen -S previewregen sudo -u www-data php occ preview:generate-all -n 4

Detach with Ctrl+A, D and reattach later with screen -r previewregen.

Skipping Folders with .nomedia

If you have folders you never want previews for (raw backups, archives, system folders), create an empty file named .nomedia inside that folder. The Preview Generator app respects this file and skips the folder entirely. This is faster than excluding paths in config.php because it does not require a scan to discover the exclusion.

This is the same convention used by Android and many media apps, so if your media library came from a phone, the .nomedia files are probably already there.

FAQ

Conclusion

Setting up the Nextcloud Preview Generator for fast photo thumbnails takes about 15 minutes of work but saves hours of waiting every week. Install the app, configure config.php with the preview providers you need, run preview:generate-all once for your existing library, then schedule preview:pre-generate with cron or a systemd timer. Once it is running, your Nextcloud gallery will scroll smoothly on both desktop and mobile, and the server load will actually drop because nothing is generating thumbnails on demand anymore.

Your next step is to run the setup on your own server and check back in a day to see the queue stats drop to near zero. If you hit a wall, the official Nextcloud help forum and the Preview Generator GitHub issues page are both very active.