How to install a phpBB extension (folder depth is everything)

Since phpBB 3.1, add-ons are extensions rather than MODs, and the rules are much stricter — which is good news: if the folder is right, it works.

The folder rule

An extension lives at:

/ext/vendor_name/extension_name/

Three levels under ext/, no more, no fewer. Inside that folder you should see at least composer.json and ext.php. A zip that unpacks to ext/extension_name/ is one level short and phpBB will say the extension is not valid — it is not broken, it is in the wrong place.

1. Back up, then upload

Dump the database and copy ext/, styles/ and config.php. Then upload the extension folder so the path above is exact, keeping permissions at 755 for folders and 644 for files.

File-upload limits are worth a look here: some extension zips contain many small files, and a host that throttles FTP will silently drop the last few. Compare the file count inside the zip with the file count on the server.

2. Enable it

In the board's ACP open Customise → Manage extensions. The extension is listed under the "Disabled" tab. Click Enable.

Then purge the cache — ACP → General → Purge the cache. phpBB caches templates and styles aggressively; a freshly enabled extension that appears not to work is usually a stale cache, not a broken extension.

3. Styles and language files

If the release ships its own style, it goes under styles/ and must be installed from Customise → Style management. Language files go under language/en/. Enabling the extension does not install a style for you.

Removing one — the two-step that matters

1. Disable — the code stops running, the data stays. Safe, reversible.
2. Delete data — only appears once disabled. This drops the extension's tables and settings. It cannot be undone, so it is the step to take a backup before.

After that, delete the folder from ext/ and purge the cache again.

Common errors translated

• “The extension … is not valid” — wrong depth, missing composer.json, or the wrong branch for your phpBB version.
• Extension enables, board breaks — PHP version too new for that extension, or a file did not upload completely. Disable it, re-upload, re-check.
• Nothing shows on the front end — permissions. Extension modules often have their own permission tab under Permissions → Group permissions.