How to Upgrade PeerTube and Regenerate Thumbnails

Last reviewed: 27 July 2026, against PeerTube 8.1.5 (latest stable). This article reproduces the official PeerTube procedure for upgrading a classic (non-Docker) install on a Linux server and regenerating thumbnails afterwards. PeerTube releases frequently, so always cross-reference the current version of the official documentation before starting. Direct links to every section used in this guide are provided below.

Official Documentation Reference

• Upgrade procedure (auto-upgrade script): docs.joinpeertube.org/install/any-os#peertube-instance
• Reconciling production.yaml: docs.joinpeertube.org/install/any-os#update-peertube-configuration
• Updating nginx configuration: docs.joinpeertube.org/install/any-os#update-nginx-configuration
• Updating systemd service: docs.joinpeertube.org/install/any-os#update-systemd-service
• Restarting PeerTube: docs.joinpeertube.org/install/any-os#restart-peertube
• Rollback procedure: docs.joinpeertube.org/install/any-os#things-went-wrong
• Regenerate thumbnails: docs.joinpeertube.org/maintain/tools#regenerate-video-and-playlist-thumbnails
• Prune storage: docs.joinpeertube.org/maintain/tools#prune-filesystem-object-storage
• Changelog (IMPORTANT NOTES per version): github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md

If you are running a Docker installation, the equivalent commands are documented at docs.joinpeertube.org/install/docker.

From PeerTube 8.1 onwards, image processing migrated to the sharp dependency, and regenerating thumbnails is explicitly recommended after upgrading.

Before You Begin

You need:

• Root SSH access to the PeerTube server.
• Your current PeerTube version, which you can check with:

  cat /var/www/peertube/peertube-latest/package.json | grep '"version"'

• The IMPORTANT NOTES section of the official changelog reviewed for every version between your current one and the latest. This is non-negotiable. Major versions (6.3, 7.2, 8.0, 8.1) require manual migration scripts that must be run in sequence. See the changelog.
• The correct Node.js version for the target PeerTube version. PeerTube 8.x requires Node >= 20.19 < 21 or >= 22.12 < 23.
• pnpm installed if you are upgrading from a pre-8.0 version, since yarn was removed in 8.0. See the dependencies guide.

Back Up the Database

The upgrade script creates its own backup, but always take an independent SQL backup before any upgrade.

SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
    cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
    sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null

Note the timestamped filename, as you will need it if you have to roll back.

Run the Upgrade Script

PeerTube ships an upgrade script that fetches the latest release, downloads it, installs node dependencies, and updates the peertube-latest symlink:

cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh

When prompted, enter the PeerTube database user password (not your system root password).

If git is installed on your system, the script also generates a config/production.yaml.new file that merges your existing configuration with any new keys introduced by the upgrade.

Reconcile Configuration Files

Three configuration files need to be checked against the new release. None should be applied blindly, so review every change.

1. PeerTube Configuration

cd /var/www/peertube && sudo -u peertube diff config/production.yaml config/production.yaml.new

Review the output for conflict markers (<<<<<<<, =======, >>>>>>>) and resolve them by editing production.yaml.new. When the merged file is clean, replace your live config:

cd /var/www/peertube && sudo -u peertube cp config/production.yaml.new config/production.yaml

2. Nginx Configuration

Compare the nginx template between the two most recently installed versions:

cd /var/www/peertube/versions
diff -u "$(ls -t | head -2 | tail -1)/support/nginx/peertube" "$(ls -t | head -1)/support/nginx/peertube"

If the upstream template has changed, apply the equivalent edits to your live config at /etc/nginx/sites-available/peertube. Test and reload:

sudo nginx -t && sudo systemctl reload nginx

3. Systemd Service

cd /var/www/peertube/versions
diff -u "$(ls -t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls -t | head -1)/support/systemd/peertube.service"

If the unit file has changed, apply the equivalent edits to /etc/systemd/system/peertube.service and reload systemd:

sudo systemctl daemon-reload

Restart PeerTube and Watch the Logs

sudo systemctl restart peertube && sudo journalctl -fu peertube

Wait for the line:

Migrations finished. New migration version schema: NNNN

The schema number depends on which version you upgraded to. Do not proceed to migration scripts until this line appears.

Run Migration Scripts

For every major version you skipped over, run the corresponding migration script. They are idempotent (safe to run multiple times), but they must be run in order.

Each script is invoked like this (replace the filename):

cd /var/www/peertube/peertube-latest && \
    sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production \
    node dist/scripts/migrations/peertube-8.1.js

The 6.3 migration in particular may take a long time on instances with many federated videos.

Regenerate Thumbnails

After every upgrade, and especially when moving to 8.1 or later, regenerate thumbnails to ensure they are processed at the correct sizes for the current release:

cd /var/www/peertube/peertube-latest; \
    sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run regenerate-thumbnails

The script reads each video's existing thumbnail file and reprocesses it. It does not generate thumbnails from scratch. If the source thumbnail file is missing from disk, the script logs an error for that video and continues with the rest.

If you see errors like Thumbnail /path/to/file.jpg does not exist on disk, those specific videos have lost their thumbnail files (commonly the result of an incomplete storage migration). The quickest fix is to open each affected video in the admin interface and upload a new thumbnail via My Library → Videos → Update → Thumbnail.

Prune Storage

Optionally clean up orphaned files left behind by interrupted transcodes, killed jobs, or deleted videos:

cd /var/www/peertube/peertube-latest; \
    sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage

The script lists candidate files and asks for confirmation before deleting. Review the count first. If it reports thousands of files, stop and investigate before confirming.

If Something Goes Wrong

To roll back to the previous version, replace OLD_VERSION and SQL_BACKUP_PATH with the actual values from your backup:

OLD_VERSION="vX.Y.Z" && SQL_BACKUP_PATH="backup/sql-peertube_prod-TIMESTAMP.bak" && \
  cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
  sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
  sudo -u postgres pg_restore -c -C -d peertube_prod "$SQL_BACKUP_PATH" && \
  sudo systemctl restart peertube

If you are on a Noiz managed PeerTube plan, you do not need to perform this procedure yourself. Contact Noiz support and the upgrade will be handled for you. If you self-manage your PeerTube install and run into trouble, Noiz support can also help on a billable basis.