Upgrading From 1.x

Introduction

This guide upgrades a native 1.x Panel, installed with the 1.x installation guide, to 2.0. First read Changes From 1.x to see which changes affect your Panel.

You install 2.0 in a new directory next to 1.x, migrate the database, then swap the directories. Your 1.x files stay unchanged, so you can switch back if something goes wrong. Game servers keep running; only the Panel goes offline.

Enter your install directory, PHP version, and web server below to fill them into the commands on this page.

Upgrading Using AI

An AI assistant is a tool you can choose to use, at your own risk. If you do, give it this guide: click Copy Markdown at the top of this page, or point it at https://docs.pterodactyl.io/v2/upgrading/upgrading-from-v1.md. Using AI With Pterodactyl has an upgrade prompt.

You are responsible for every command you run, whoever suggested it. Check each one against this page, keep your backups, and try the upgrade on a copy first. If something breaks, the community can help with the steps on this page, not with what an assistant told you to do.

Before You Upgrade

Update to the Latest 1.x Release

You need Panel 1.12.0 or newer. We recommend updating to the latest 1.x release first with the 1.x update guide.

If your database is from an older release, the upgrade stops before changing anything and asks you to update 1.x first.

Install the Intl PHP Extension

Pterodactyl 2.0 needs PHP 8.3 or newer and the intl extension. The 1.x installation guide does not install intl, so add it:

apt install php8.3-intl

If php -v shows a version older than 8.3, upgrade PHP first with Upgrading PHP.

Update Your Billing Module

Pterodactyl 2.0 removes the Application API's nest endpoints, so any billing module that requests /api/application/nests/... stops working after the upgrade.

If you use the official WHMCS module, update it before you upgrade the Panel; the updated module works with 1.x and 2.0. For any other billing module, ask its developer whether it supports 2.0.

Upgrade Steps

The commands use the www-data user and pteroq service from the 1.x installation guide, plus the install directory and PHP version from Your setup above. Change anything else that differs on your system.

Enter Maintenance Mode

Put the Panel into maintenance mode and stop the queue worker:

cd /var/www/pterodactyl
php artisan down
systemctl stop pteroq

Back Up Your Panel

Back up the database, your .env file, and the Panel directory:

mysqldump --single-transaction --routines --triggers panel > /root/panel-1.x.sql
cp /var/www/pterodactyl/.env /root/panel-1.x.env
tar -czf /root/panel-1.x-files.tar.gz -C /var/www/pterodactyl .

Keep a copy of your .env file somewhere safe. It holds your APP_KEY, without which the Panel cannot read node tokens, database passwords, two-factor secrets, or API keys.

Download 2.0

Download the latest beta and unpack it in a new directory:

mkdir /var/www/pterodactyl-2.0
cd /var/www/pterodactyl-2.0
curl -L https://github.com/pterodactyl/panel/releases/download/v2.0.0-beta.2/panel.tar.gz | tar -xzv

Then copy your .env file from 1.x. It needs no changes:

cp /var/www/pterodactyl/.env /var/www/pterodactyl-2.0/.env

Do not run php artisan key:generate. The Panel must keep using your existing key.

Install Dependencies

Install the PHP dependencies with Composer:

COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

If Composer reports a missing PHP extension, install it and run the command again. To check that PHP has everything the Panel needs, run:

composer check-platform-reqs --no-dev

Migrate the Database

Put the new directory into maintenance mode too, then run the database migrations:

php artisan down
php artisan migrate --force

The migration took under ten seconds on our test installation. It adds tables for tags and extensions and does not change your existing data.

1.x updates also ran the database seeder to update the default eggs. In 2.0 this is optional. To update the default eggs, run:

php artisan db:seed --force

Switch to 2.0

Give the web server user ownership of the new directory, then swap the two directories:

chown -R www-data:www-data /var/www/pterodactyl-2.0
mv /var/www/pterodactyl /var/www/pterodactyl-1.x
mv /var/www/pterodactyl-2.0 /var/www/pterodactyl

Next, add the /assets/ block to the Panel's web server configuration. It serves public/assets, where themes and extensions publish their files, as plain files: it never passes them to PHP, and it refuses hidden files. The full configuration is on Webserver Configuration.

Add this block inside the Panel's server block in /etc/nginx/sites-available/pterodactyl.conf, next to location /. If you use SSL, add it to the server block that listens on port 443:

location ^~ /assets/ {
    location ~ /\. {
        deny all;
    }

    try_files $uri =404;
}

Then check the configuration and reload NGINX:

nginx -t
systemctl reload nginx

Finally, clear the caches and restart PHP and the queue worker:

cd /var/www/pterodactyl
php artisan optimize:clear
systemctl restart php8.3-fpm
systemctl start pteroq

Exit Maintenance Mode

When you are ready, bring the Panel back online:

php artisan up

What Stays the Same

You do not need to change these:

• Server configuration. Your cron entry and pteroq service work unchanged.
• Environment file. Your .env file works as is. 2.0 still reads 1.x setting names such as CACHE_DRIVER.
• Wings. Wings 1.13.2 and 1.13.3 work with the 2.0 Panel. You can upgrade Wings later.
• Users. Passwords, two-factor authentication, and SSH keys keep working.
• API keys. Existing Application and Client API keys keep working.
• Servers. Servers, subusers, schedules, backups, databases, and SFTP access keep working.
• Settings. Your Panel settings are kept.

After Upgrading

Review Egg Tags

Pterodactyl 2.0 replaces nests with tags. The upgrade converts your nests like this:

• A nest named after a built-in game, such as Minecraft or Rust, gives its eggs that game's tag.
• A custom nest with two or more eggs becomes a tag with the same name.
• A custom nest with only one egg does not become a tag. Its egg has no tag after the upgrade.

Check your eggs after the upgrade and add any tags you need.

The nests table stays in your database, but 2.0 no longer updates it.

Keep Your 1.x Files

Keep /var/www/pterodactyl-1.x and your backups until you are sure the upgrade worked. You need them to go back to 1.x.

Troubleshooting

The Migration Stops With a Missing Migration Error

If your database is missing a 1.x migration, the upgrade stops with a message like this:

This database is missing 1 Pterodactyl Panel 1.x migration(s), starting with 2024_07_13_091852_clear_unused_allocation_notes.

Nothing has been changed yet. To fix it:

1. Bring 1.x back online by running php artisan up and systemctl start pteroq in /var/www/pterodactyl.
2. Update 1.x to the latest 1.x release and run php artisan migrate --force.
3. Start this guide again from the beginning.

Rolling Back

To go back to 1.x, swap the directories back and restore your database backup:

cd /var/www/pterodactyl
php artisan down
systemctl stop pteroq

mv /var/www/pterodactyl /var/www/pterodactyl-2.0-failed
mv /var/www/pterodactyl-1.x /var/www/pterodactyl

mysql -e 'DROP DATABASE panel; CREATE DATABASE panel;'
mysql panel < /root/panel-1.x.sql

cd /var/www/pterodactyl
php artisan cache:clear
php artisan config:clear
php artisan view:clear
systemctl restart php8.3-fpm
systemctl start pteroq
php artisan up

Do not use php artisan migrate:rollback. It cannot undo the upgrade.

Rolling back only restores the Panel. Anything 2.0 changed outside the Panel stays changed:

• Servers created on 2.0 still exist on your Wings nodes. Delete their files by hand.
• Database passwords changed on 2.0 no longer match. Rotate them again from 1.x.
• Backups created on 2.0 stay in your backup storage.

Any other changes made in the Panel after the upgrade are lost.

Known Limitations

This guide has only been tested with Panel 1.15.1, MariaDB 10.11, and Wings 1.13.2 on Ubuntu 24.04. Not yet tested:

• Large production databases.
• MySQL, and other MariaDB versions.
• Moving from a native installation to the Docker image.
• HTTPS, multiple nodes, server transfers, and S3 backups.
• Extensions.