Install XenForo add-ons from the command line

Install, upgrade and rebuild add-ons from the command line

XenForo's cmd.php runs installs and upgrades without browser timeouts. The commands you need, and when to use them.

Updated Sep 27, 2026 3 min read By the D.C Style team

Before you start

SSH access to your server

PHP available on the command line (the php command)

Every XenForo forum includes cmd.php, a command-line tool that does the same jobs as the Add-ons page: install, upgrade, disable and more. Because it runs on the server rather than in your browser, it has no page time limit. That makes it the reliable choice for large forums and for any upgrade that keeps timing out.

Getting started

Connect to your server over SSH and change to your XenForo root, the folder that holds cmd.php and admin.php:

cd /path/to/your/forum
php cmd.php list

list prints every command available, including the ones add-ons add. Add-ons are referred to by their ID, which matches their folder under src/addons. The add-on in src/addons/DC/Thumbnail is DC/Thumbnail.

Tip: Run these commands as the same system user that owns your forum files where you can. Files created by a different user can leave the web server unable to update them later.

Install an add-on

Upload the contents of the add-on's upload folder as usual, then run:

php cmd.php xf:addon-install DC/Thumbnail

You can also skip the FTP step and point the command at the zip file you downloaded:

php cmd.php xf:addon-install /path/to/the-add-on.zip

Upgrade an add-on

Upload the new files over the old ones, then run:

php cmd.php xf:addon-upgrade DC/Thumbnail

This command also accepts the path to a zip file. As in the Admin CP, you can skip versions: every upgrade step between your version and the new one runs in order. More on upgrading.

Other useful commands

Command	What it does
`xf:addon-list`	Lists installed add-ons with their IDs and versions. Add `--active` or `--inactive` to filter.
`xf:addon-disable DC/Thumbnail`	Switches an add-on off and keeps its data. With no ID, it disables every enabled add-on.
`xf:addon-enable DC/Thumbnail`	Switches it back on. With no ID, it enables every disabled add-on.
`xf:addon-rebuild DC/Thumbnail`	Re-imports the add-on's data (options, phrases, templates and so on) from its files. Useful when something is missing after an upload.
`xf:addon-uninstall DC/Thumbnail`	Uninstalls the add-on and removes its data. Read this first.
`xf:file-check`	Runs the file health check. Add `--addon=DC/Thumbnail` to check one add-on.
`xf:rebuild-master-data`	Rebuilds XenForo's own core data.
`xf:run-jobs`	Runs any background jobs that are waiting. Cron and the job runner.

Most add-on commands also accept --force, which skips XenForo's safety checks. Leave it off unless we ask you to use it while helping you in a ticket.

When the command line saves the day

An upgrade times out in the browser. Run the same upgrade with xf:addon-upgrade.
An add-on has broken the site. xf:addon-disable can often switch it off even when you cannot reach the Admin CP. If that fails too, this guide has a one-line fallback in config.php.
A long migration or rebuild. Some add-ons ship their own commands for heavy work, such as moving files in Google Drive Attachments or rebuilding thumbnails in Thumbnail. They show up in php cmd.php list.

Still stuck? Open a support ticket and paste the full command you ran and everything it printed.