Migrating from Pterodactyl

Move a Pterodactyl panel to FeatherPanel with feathercli migrate. What is imported, the 15 migration steps, and how to switch each node from Wings to FeatherWings.

On this page

FeatherPanel imports a Pterodactyl panel through the Pterodactyl Migration Agent, which is the migrate command of FeatherCli. The agent reads the Pterodactyl database and sends the data to the importer endpoints of your new panel. The direct HTTP import in older versions is gone.

What is imported

The migration runs 15 steps in this order and records progress in .migration-progress.json in the current directory, so an interrupted run can resume:

Panel settings
Locations
Nests, as realms
Eggs and their variables, as spells
Nodes
Database hosts
Allocations
Users, with their bcrypt password hashes
SSH keys
Servers and server variables, keeping their UUIDs
Server databases
Backups
Subusers
Schedules
Schedule tasks

The migration decrypts values Pterodactyl stored with its APP_KEY, which is why it needs the Pterodactyl .env or the key itself.

If Blueprint is installed on the Pterodactyl panel, the agent warns that its database changes may break the migration and asks you to confirm with --confirm-blueprint.

1. Prepare FeatherPanel

Install FeatherPanel on a new server or next to Pterodactyl, and register the first account. Do not create nodes, locations or servers: the importer checks that the panel has at most one user and nothing else.

Open /admin/pterodactyl-importer. The page shows the prerequisite check, lets you create an API key for the agent, and lists the commands below. The key needs the admin.root permission.

2. Install and configure FeatherCli

On the Pterodactyl server:

curl -sSL https://get.featherpanel.com/stable.sh | bash   # choose [3] CLI
feathercli config setup                                   # panel URL and the API key from step 1
feathercli config test

3. Run the migration

feathercli migrate check --pterodactyl-dir /var/www/pterodactyl
feathercli migrate --pterodactyl-dir /var/www/pterodactyl

The agent reads /var/www/pterodactyl/.env, connects to the Pterodactyl database and runs php artisan down to stop changes during the import. If that fails it asks you to run it yourself.

For a Dockerised Pterodactyl, export the database and .env, then let the agent load the dump into a staging MySQL server it can reach:

docker compose exec database mariadb-dump -u root -p"$MARIADB_ROOT_PASS" panel > panel.sql
docker compose exec panel cat /app/var/.env > panel.env

feathercli migrate \
  --sql-dump ./panel.sql \
  --env-file ./panel.env \
  --staging-db-host 127.0.0.1 \
  --staging-db-user root \
  --staging-db-password 'your-mysql-password'

Use --app-key instead of --env-file if you only have the key. --sql-dump and --pterodactyl-dir cannot be combined.

Flag	Meaning
`--confirm-migrate`	Skip the final confirmation
`--confirm-blueprint`	Continue although Blueprint is installed
`--reset`	Forget saved progress and start from step 1
`--staging-db-port`	Port of the staging database

4. Switch each node to FeatherWings

The migration moves data, not daemons. Right after it finishes, do this on every node:

sudo systemctl disable --now wings
curl -sSL https://get.featherpanel.com/installer.sh | bash   # choose [2] Wings, install only

Then get the node’s configuration from FeatherPanel (the node page in the admin area) and apply it with featherwings configure --join-data ... --override, or place it in /etc/featherpanel/config.yml, and start the service:

sudo systemctl enable --now featherwings

Imported nodes keep their data directory, so FeatherWings finds the existing server files in /var/lib/pterodactyl/volumes without copying anything. Server UUIDs are unchanged.

After the migration

Sign in with a migrated user and open a few servers: console, files, backups.
Check that every node is green and that schedules run.
Point your domain at FeatherPanel when you are satisfied, and keep the Pterodactyl backup for a while.
If you used the Pterodactyl API in other tools, read the API reference. The agent’s closing message recommends a Pterodactyl API compatibility plugin for existing integrations.

For a side by side comparison of the two panels, see FeatherPanel vs Pterodactyl.

Frequently asked questions

Do users need new passwords after migrating from Pterodactyl?

No. Pterodactyl stores bcrypt password hashes and the migration copies them unchanged, so users sign in to FeatherPanel with their existing passwords.

Are server files copied during the migration?

No. Server files stay on the nodes. Imported nodes keep Pterodactyl's data directory (/var/lib/pterodactyl/volumes by default), and FeatherWings uses it once you switch the node over.

Can I migrate into a FeatherPanel that already has servers?

No. The importer requires a clean panel with at most one user and no nodes, locations, realms, spells, servers, databases or allocations.