Extensions

Introduction

Extensions add features to the Panel without changing its code. They can add pages, detail tabs, table columns, and API endpoints, place content on existing pages, and store their own data.

Each extension is a package described by an extension.json file and installed in the Panel's extensions directory.

To build your own extension, see Building Extensions.

Installing Extensions

Extensions are distributed as .pteroext files, which are zip archives of the extension's directory.

From the Admin Area

Open Admin → Extensions, click Install, and choose a .pteroext or .zip file of up to 50 MB. Select Enable after install to enable it right away.

From the Command Line

Pass p:extension:install a .pteroext file, a .zip file, or an unpacked extension directory:

php artisan p:extension:install /path/to/server-notes.pteroext --enable

--enable enables it after install. Then give the web server user ownership of the new files:

chown -R www-data:www-data /var/www/pterodactyl/extensions /var/www/pterodactyl/public/assets/extensions

Installing an unpacked directory copies all of it, including development files such as node_modules. Install a packaged .pteroext file to avoid this.

Enabling and Disabling Extensions

An installed extension does nothing until you enable it. Enable and disable extensions from Admin → Extensions, or with Artisan:

php artisan p:extension:enable server-notes
php artisan p:extension:disable server-notes

Before enabling an extension, the Panel checks its version requirements, required extensions, and built frontend files. It then runs the migrations in database/migrations and publishes the assets before marking the extension enabled. If activation fails, the extension keeps its previous state and asset version.

An extension can replace supported parts of the Panel's presentation. Enabling it activates those replacements; disabling it restores the native views after a reload. Each component can be replaced by only one enabled extension. A conflicting enable or update fails and names the component and its existing owner.

Required extensions must be enabled and meet the declared version constraints. Before disabling or removing an extension, disable the extensions that depend on it.

Disabling an extension turns off its pages, API endpoints, and frontend code, but keeps its files, data, and settings.

Installing, enabling, disabling, or removing an extension refreshes cached routes and signals queue workers to restart. Users must reload the Panel to get the current frontend code.

Configuring Extensions

To change an extension's settings, open Admin → Extensions and click the extension's settings button. Settings only appear for enabled extensions.

Settings are stored in the Panel's database. Secret settings are encrypted and appear blank in the form; leave a secret field blank to keep its saved value. A password field is only encrypted if the extension declares it as a secret.

Changes to frontend settings take effect after a page reload.

Updating Extensions

To update an extension, install the new package the same way. The extension keeps its enabled or disabled state. If it is enabled, the Panel checks compatibility and runs the package's migrations before activating it.

If installation or activation fails, the Panel restores the previous package, version, enabled state, and asset version. It cannot undo database schema changes made by migrations. Keep a database backup, and check for partially applied migrations before trying again.

Published assets use versioned directories. The Panel keeps earlier builds so open browser sessions can still load their screen files during an update. Reload the page to use the installed version.

Removing Extensions

Remove an extension from Admin → Extensions, or with Artisan:

php artisan p:extension:remove server-notes

Removing an extension deletes its files and published assets. Its database tables and settings are kept, so its data is still there if you install it again. To remove the data, drop the extension's tables by hand. By convention, their names start with ext_ followed by the extension's ID.

Listing Extensions

To list every installed extension and its state, run:

php artisan p:extension:list

+--------------+--------------+---------+-----+---------+-------+
| ID           | Name         | Version | UI  | State   | Error |
+--------------+--------------+---------+-----+---------+-------+
| server-notes | Server Notes | 1.0.0   | yes | enabled |       |
+--------------+--------------+---------+-----+---------+-------+

Configuration

Set these environment variables in your .env file:

If an extension breaks your Panel, set PTERODACTYL_EXTENSIONS_ENABLED=false to turn off all extensions, then find and disable the broken one.

The web server user must be able to write to the extensions directory and to public/assets/extensions, or you cannot install or remove extensions from the admin area.

Docker

If you run the Docker image, keep /app/extensions and /app/public/assets/extensions on volumes, or your extensions are lost when the container is recreated. The example Compose file already does this.

Troubleshooting

An Extension Shows an Error

If an extension fails while the Panel starts, the Panel skips it and keeps running. The error appears on the extension's card in Admin → Extensions and in the Error column of p:extension:list. The Panel retries the extension on every request, so the error clears once the problem is fixed.

An extension marked invalid has a broken extension.json file and cannot be enabled until the file is fixed.

An Extension's Page or Content Does Not Appear

When an extension's content fails to load, users see a recovery action: a retry for render failures, or a page reload for failed screen files. Admin → Extensions also shows frontend failures seen by the current browser. The browser's developer console has the full error.

Check that the extension is enabled, and reload the page. The Panel only loads extension changes on reload.

Fields that an extension adds to an admin form, such as the server or user forms, are hidden on an edit page when the extension's stored values cannot be loaded. This stops a save from overwriting them. The cause is recorded on the extension's card in Admin → Extensions.