A phpBB board becomes a XenForo board by import, not by “converting the files.” You install XenForo, you install the separate Importers add-on from your customer area, you point Tools → Import data at a copy of the phpBB database, you run the steps, you rebuild caches, you put redirect scripts in front of the old URLs. The source is never modified. The destination is only as safe as the backup you took before you hit Start.
This is not the host-move / backup / empty-to-empty clone article (that is the operational backup piece in this series). This is the phpBB-specific path: which versions the official list names, when you may retain IDs, how merge-by-email works, why the CLI exists, and how import_log becomes 301s. It is also not the IPS vs XenForo comparison. You already chose.
Official sources: XenForo importing overview, configuration, run, completion, and redirection chapters (docs.xenforo.com/manual/importing/…). Community: public reports of phpBB 3.3.15 → XenForo 2.3.10 succeeding. Official “at time of writing” source list includes phpBB 3.2 to 3.3. It does not list phpBB 3.1 or 3.0. Do not invent that support.
What the official importer will take
Importers are not in the XenForo zip you uploaded to the web root. They are a separate add-on downloaded from the XenForo customer area. Install that add-on on the destination XenForo before Tools → Import data will show sources.
Official list at the time the 2.3 manuals were written:
- XenForo 2.x
- vBulletin 3.6 to 5.3
- IPS 4.x
- phpBB 3.2 to 3.3
- SMF 2.0
- MyBB 1.8
- Discourse 3.x
Read the phpBB line twice. 3.2 and 3.3. A 3.1.x or 3.0.x board is outside that list. The honest options are: upgrade phpBB to 3.2 or 3.3 first (on a copy), then import; or treat 3.1 as out of scope for the official add-on and stop. This article will not describe a 3.1 importer that XenForo does not list.
What an import can bring across, official overview wording: users, forums, threads, posts, private messages, “along with various other data.” The phpBB importer’s exact step list appears in the ACP after you select that source. It is not reprinted as a public phpBB-specific notes page the way vBulletin has import-notes-vbulletin. Believe the step screen. Do not skip a dependency (posts need threads; threads need forums).
Architecture of a safe cutover
Official speed advice is also safety advice: do not import over the WAN from production phpBB into production XenForo. Network latency turns every step into thousands of remote queries.
The shape that finishes in hours instead of a weekend:
- Snapshot phpBB — database dump +
files/(attachments, avatars) as phpBB stores them. Leave production phpBB running until the final cut. - Build a fast working box (or a quiet VPS) with both databases local: a restored phpBB copy and a fresh XenForo 2.3 with the Importers add-on.
- Import there. Measure. Fix mapping. Repeat from backup if you selected the wrong steps.
- Cut over: put XenForo on the public hostname, install redirect scripts where phpBB used to live, point DNS / vhost, turn Board active on.
A one-box “import from remote production” will work. Official says it will be massively slower. It also means a mistake writes into the live XF database you already showed members.
If the destination XenForo is already a live community (you are absorbing phpBB into an existing XF), you cannot retain content IDs. Plan merge-by-email. Plan that thread IDs will be new. Plan redirects via the import log, not via “the numbers stayed the same.”
Before Tools → Import data
Work this list in order. Skipping a row is how you restore twice.
1. Match the supported range
On phpBB: ACP → System → General (or your 3.3 equivalent) and read the version. You need 3.2.x or 3.3.x. Community report: 3.3.15 imported into XF 2.3.10. That is a data point, not a promise that every extension will survive. phpBB 3.3.16+ is still 3.3; the official line is the minor series, not a single patch.
If you are on 3.1, upgrade phpBB on a copy until you are in 3.2–3.3, then import that copy. Do not ask the XF importer to pretend 3.1 is 3.2.
2. Install XenForo as if it were empty — if you want IDs
Retain content IDs is allowed only on a XenForo that has no threads and no posts. Official wording: “a completely empty XenForo installation.” Practically: a fresh install you have not used as a community. Creating a couple of test posts to “see if XF works” is enough to disqualify retain-IDs. If you already posted, either wipe and reinstall XF or import without retaining IDs.
Empty still has the default Unregistered / unconfirmed, Registered, Administrative, Moderating groups. That is expected. Those four cannot be removed. Imported phpBB groups will land as additional groups; you will tidy them after.
3. Install the Importers add-on
Customer area → Importers package → upload / install like any add-on → confirm it is enabled. Tools → Import data should then list sources. If the page is missing, the add-on is not installed. It is not a 2.3 core feature you forgot to tick.
4. Backup the destination
Official warning, not optional:
- Full backup of the XenForo database
- The
data/directory - The
internal_data/directory
phpBB source files and the source database are never modified. The thing you will destroy if the import is wrong is XenForo. A backup of XF is the only rewind. Restoring files and database together, same XF version — the configuration mistakes article already covers a restore that boots the wrong Board URL.
5. Close the destination board
Setup → Options → Board active (basic board information): turn the board off for the duration. Official: it is a good idea. Members registering into a half-imported user table is how you get two “Admin” accounts and a merge nightmare.
phpBB can stay up until the final DNS flip if you are importing from a copy. If you are importing from the live phpBB database, you are racing new posts. Don’t. Snapshot, import the snapshot, freeze phpBB when you cut.
6. Put attachments where the importer can see them
phpBB 3.2/3.3 attachments and avatars live on disk (and sometimes in paths you customized). The importer’s step configuration will ask you to confirm paths. Official: some importers guess from leftover config if XF is installed in the same directory phpBB used to occupy. If you installed XF in a new vhost, you will type the paths. Have them ready. A wrong avatar path is a successful import with empty faces.
Configuring the import
Tools → Import data. Choose the phpBB source (grouped with the other XenForo-targeted importers). Continue.
Database connection
You will be asked for the source (phpBB) database credentials. If XF sits in phpBB’s old directory and a phpBB config.php is still there, the importer may auto-fill. Check every field anyway. Connecting to production by accident is a human error the form cannot prevent.
Continue. XF will try the connection. Failure here is credentials, host, or “phpBB is not on this box.” Fix it before you think about steps.
Steps, dependencies, and what you may uncheck
Next screen: a list of steps, each a data type. Official: some steps depend on others — posts need threads, threads need forums. You may uncheck steps you truly do not want (example official gives: import users but skip avatars).
Once the import has started you cannot go back and change the step set. Read the list twice. If you need avatars, attachments, private messages, or profile fields, they must be checked now.
Retain content IDs
This checkbox is the one people click because it sounds like SEO.
- On (only if XF has no threads/posts): a phpBB thread with ID 2563 becomes XF thread 2563. Nice for mental maps. Not required for redirects.
- Off (default): sequential new IDs. Official: faster and more reliable in most cases. Redirect scripts exist because IDs will not match.
If the destination already has conversations, you cannot retain IDs. Official is explicit. Do not empty xf_thread by hand to “make it empty.” Reinstall.
Import log table
You must name a table that will store the old ID → new ID map. Official suggestion: import_log (lowercase, digits, underscores). The table must not already contain data. If it exists and is dirty, official says TRUNCATE TABLE your_table_name; only if you are certain that data can die.
This table is not optional if you want redirects later. The redirection scripts query it. Write the name down. import_log_phpbb_20260616 is a better name than import_log if you might import twice.
User merge
If the importer brings users (it will), you will be asked roughly:
- Merge users with the same email address?
- Merge users with the same username?
Official: enable same email in almost every absorb-into-live-XF scenario. Two rows with admin@example.com are the same person. Official: same username depends on whether you know that Admin on phpBB is Admin on XF. If you merge, phpBB Admin’s posts become XF Admin’s posts. If you do not, you get Admin2.
On a fresh empty XF that only has your installation admin, think carefully. That installation admin’s email might match your phpBB founder. Merge by email then folds the founder into the XF admin you already use — usually what you want. Merge by username when both sides invented an Admin who is not the same human is how you attach 40,000 posts to the wrong person.
Browser vs CLI
Official: two runners, same job, both resumable.
| Runner | How | Speed | When |
|---|---|---|---|
| Browser | Stay on Start import, click through each completed step | Slower | Tiny boards, no SSH, watching counters |
| CLI | From the XF root: php cmd.php xf:import |
Significantly faster | Any board you care about |
Browser
Select Browser importer, Start import, follow prompts. Counters increment per step. You must prompt the next step each time one finishes. Closing the tab mid-step is an interruption. Official: you can resume via Tools → Import data, but some data may be lost; aim to let it finish.
CLI
- Leave the browser on the Start import page (configuration is already stored).
- SSH to the box.
cdto the XenForo root — the directory that containscmd.php. Ifcmd.phpis not there, you are in the wrong folder.- Run:
php cmd.php xf:importAll steps run sequentially without you clicking. Progress prints per step.
Use the same php binary the site uses (PHP 8.x with the extensions XF 2.3 wants). A host that has php → 7.4 on the CLI and 8.3 in php-fpm is a classic own-goal.
Interrupted? Official: run Tools → Import data or run the CLI command again. Do not start a second import into a half-written board. Resume or restore from the XF backup and start clean.
Completing the import
When the last step finishes, the ACP shows Complete import (CLI users: refresh the browser). You get a summary: each step, time taken, item counts. Read it. Zero users or zero posts is a failed path, not a quirk.
One thing remains: rebuild caches. Official: click Complete import. That rebuild can be moments or minutes depending on volume. Do not skip it. Do not open the public site until it finishes. Search, counters, last-post caches — this is when they become true.
After that, the board is technically imported. It is not cut over. Permissions, styles, and URLs still look like a phpBB costume until you walk them.
Redirection scripts use the import log
Official Redirection chapter: some importers ship scripts that sit in the old software’s URL space, look up the request in the import log table, and 301 to the new XF URL. Search engines update. Bookmarks survive. Retain-IDs is not a substitute for this.
vBulletin has a dedicated XenForo Redirects for vBulletin product called out in the manuals. phpBB does not get that same named product paragraph. What you still have:
- The import log table you named
- Whatever redirect scripts the phpBB importer provides in that Importers add-on package (they are add-on files, not core XF)
- Your web server
After import, read the Importers add-on archive and the ACP completion text for phpBB-specific redirect files. Install them on the hostname/path where phpBB used to answer (viewtopic.php?t=123 and friends). Point them at the XF install and at the same table name you configured.
If the importer’s package has no phpBB redirect script you can find, you still have the log table. A small custom 301 map can be built from import_log — that is engineering, not an official one-click. Do not invent a “phpBB Redirects” SKU that XenForo does not sell.
Friendly URLs on the XF side (Setup → Options → Search engine optimization) change what the destination looks like (/threads/title.123/ vs /index.php?threads/…). Configure that before you generate public redirects, or you will 301 twice. The SEO article in this series owns the switch. Here: pick one URL shape, then redirect onto it.
Official: XF does not rewrite URLs inside post text as a general import feature (community import threads repeat this). A phpBB [url] to viewtopic.php?t=99 in an old post will still say that. Redirect scripts make that old URL land on the new thread. That is why the log table exists even if you retained IDs.
After the caches rebuild
Walk these in the first hour, on the closed board, before DNS.
Groups and permissions
phpBB groups are not XenForo groups. Imported ranks and group names will appear as extra groups. Official default groups stay: Unregistered / unconfirmed, Registered, Administrative, Moderating. Every imported human should end with Registered as primary — the same rule as a native XF user. If the importer left a phpBB “Administrators” group as someone’s primary, fix it before you open the door. Permissions and configuration mistakes both exist because this one switch looks like a bug later.
Analyze permissions for the founder, a moderator, a normal member, and a guest. phpBB’s forum-ACL mental model does not map 1:1 to XF’s Never > Yes > No plus node Inherit. Private staff forums in phpBB should become Private node + Yes on the staff groups, not a pile of Never on Registered.
Avatars and attachments
If faces are missing, the path you typed was wrong or data/ was not writable. Official: an empty data/ / internal_data/ after a file-level move is how avatars vanish. Re-running only the avatar step is not something the official run chapter offers after Complete. Restore XF from backup and import again with the correct path, or treat avatars as a re-upload project.
Users who must reset
phpBB password hashes are not XF’s native hash. The official importer’s job is to bring users in so they can log in — typically by verifying the old hash on first login and re-hashing, or by sending them through lost password. The public import chapters do not print the phpBB-specific hash sentence. Operationally: test login as a normal imported user on a staging copy before you announce “just use your old password.” If that login fails, your announcement is lost password, not “the importer is broken.” Lost-password flood limits and CAPTCHA are in the security article.
Styles, languages, BBCode
phpBB styles do not import as XF styles. You will have the default 2.3 style plus whatever you install. Custom phpBB BBCode may become messy markup. Plan a staff pass on the ten stickies everyone still reads. Smilies and attachment markup are importer-dependent; check a post that had both.
Board URL, cookie path, cron
After you deploy the imported database to production, set Board URL and cookie path to the public site. Wrong cookie path = everyone looks like a guest — already in mistakes. Turn Board active on only when redirects and HTTPS are in place.
phpBB 3.3.15 → XF 2.3.10 is a known success path
A public XenForo community thread titled Successful Migration from phpBB 3.3.15 to XenForo 2.3.10 (April 2026) reports a completed import, including a board on the order of 150,000+ messages, after tests on copies. That is evidence the official 3.2–3.3 importer is the right tool on current 2.3, not a museum piece.
It is not a warranty. Extensions on the phpBB side (extra tables, custom profile fields, extra BBCode) may not have a step. Official: you may uncheck steps; there is no official “import this phpBB extension” toggle. Anything not in the step list stays in the phpBB dump you kept.
A worked sequence (empty XF, retain IDs, CLI)
- Snapshot phpBB 3.3.x: SQL dump + files. Confirm version ≥ 3.2 and ≤ 3.3.x.
- New VPS. Restore phpBB dump as database
phpbb_src. Install fresh XF 2.3. Do not post a welcome thread. - Install Importers add-on. Confirm Tools → Import data.
- Backup XF database +
data/+internal_data/. Board active = no. - Import data → phpBB → credentials for
phpbb_src→ all steps you need → Retain content IDs = yes → log tableimport_log_phpbb→ merge same email = yes → merge same username = only if you intend it. - SSH, XF root,
php cmd.php xf:import. Let it finish. - Browser: Complete import. Wait for cache rebuild. Read counts.
- Log in as founder. Analyze permissions. Fix primaries. Check one avatar, one attachment, one PM, one poll if you imported polls.
- Install phpBB redirect scripts (from the importer package) on the old URL space, pointed at
import_log_phpbb. - Deploy XF files + DB to production (or promote this box). Fix Board URL. HTTPS. Board active = yes. Watch the first 50 redirected hits.
If step 7 shows zero posts: do not debug live. Restore the XF backup from step 4 and start at step 5 with logging.
Checklist
- phpBB is 3.2 or 3.3 (not 3.1; not “we think 3.3 is close enough to 3.1”)
- Importers add-on is installed from the customer area, not assumed in core
- Destination XF backup: database +
data/+internal_data/ - Board active off on XF
- Source is a copy on the same fast box when the board is large
- Step list includes every type you will miss tomorrow; you cannot add a step mid-run
- Retain content IDs only if XF has no threads/posts
- Import log table name written down; table empty or new
- Merge by email decided; merge by username decided separately
- Runner is
php cmd.php xf:importunless the board is tiny - Complete import clicked; caches rebuilt
- Redirects use the import log, not hope
- Registered is primary for imported humans
- A normal user login was tested on staging
- phpBB dump kept offline for 90 days
What this is not
It is not a phpBB 3.1 guide. Official does not list 3.1.
It is not a style conversion. phpBB skins do not become 2.3 styles.
It is not the Discourse or IPS direction. Official can import Discourse 3.x into XF; that is a different source on the same Tools → Import data screen.
It is not a reason to skip HTTPS, 2FA, or login limits on the new board. Day-one security still applies. Day-one email / push still applies or nobody gets the “we moved” mail.
Takeaways
- Official phpBB support is 3.2–3.3 via a separate Importers add-on, started at Tools → Import data.
- Retain content IDs only on an XF with no threads/posts. Redirects do not depend on it; they depend on
import_log. - Backup XF (DB +
data/+internal_data/). Close the board. Never write the source. - Merge same email unless you have a reason not to. Merge usernames only when you know they are the same person.
php cmd.php xf:importis the real runner. Browser is for small tests.- Click Complete import. Then fix groups, paths, Board URL, and 301s.
- Community has already done phpBB 3.3.15 → XF 2.3.10. Use that as confidence, not as a substitute for a copy-first rehearsal.
Import on a copy. Cut over once. Keep the dump until the 301s go quiet.