Installation and upgrades

Installing and upgrading XenForo follow very similar processes. At a very basic level, the general process is:

  1. Download XenForo and extract the files locally.
  2. Upload the contents of the upload directory within the extracted files to your server.
  3. Point your browser to the install/upgrade system and follow the on-screen instructions.

If you have any problems or questions with this, please submit a support ticket and we will help you through the process.

More detailed instructions are provided below.

Note

Please ensure that your server meets XenForo's requirements.

Installing XenForo

To install XenForo you will need the following things:

  1. Your XenForo customer account details
  2. An FTP client (such as FileZilla or WinSCP)
  3. The FTP login details for your server
  4. An empty MySQL database on your servers and the details to access it

1. Downloading

To begin, you must first download the zip file that contains XenForo from the XenForo customer area.

If you have not already, you must provide information about the site that will be running XenForo. Once this has been done, a download link will be visible. Click this and follow the on-screen instructions.

Note

Ensure that you deselect the Download the upgrade package only option when downloading to do a fresh install.

2. Uploading

On your computer, unzip the file that you downloaded in step 1. Within it, you will see an upload directory. You will be uploading the contents of this directory to your server (not the directory itself).

Now use your FTP client to connect to your server and create the directory where you want to install XenForo. For example, if you want to access XenForo via example.com/community/, you would create a community directory within your webroot (such as your public_html directory). You will need to make a note of what URL this corresponds to for the next step. This will be known as your "XenForo root URL".

Note

If you want to install XenForo at the root of your domain, you will generally not need to create a directory. However, XenForo must be installed into a directory that isn't already being used to display pages.

Use your FTP client to upload the contents of the upload directory that was contained within the zip that you extracted earlier to the directory you just created on the server. Ensure that all files and sub-directories are uploaded. If done correctly, once uploaded, you should see files such as admin.php and css.php directly within the directory you created on your server.

Uploading may take some time. Please do not proceed until the upload is complete. Keep your FTP client open as you may need it in the next step.

3. Installing

Now you're nearly ready to start the XenForo installation.

Direct your browser to the install directory under your XenForo root URL. For example, if your XenForo root URL was www.example.com/community/, you would direct your browser to www.example.com/community/install/. If you have the correct URL, you should see the XenForo installer.

Depending on server configuration, you may receive an error about certain directories not being writable. If so, follow the "setting directory permissions" steps. If you receive any other error messages, your server does not meet XenForo's requirements and your host will need to make changes to their PHP configuration.

Setting directory permissions

Depending on your PHP configuration, you may need to manually make certain directories writable. If this is needed, a message will be displayed when starting the installation.

If you receive this message, open your FTP client and navigate to your XenForo root directory (the directory your created earlier). You should see the data and internal_data directories. You will need to change permissions on these two directories.

In Linux, these should be "chmod 0777". You can generally do this via your FTP client by making sure that the directory has read, write, and execute permissions for user, group and world. In Windows/IIS, you need to grant the "Full Control" permission to the IUSR_ account.

Once complete, refresh the installer. If changed correctly, the error message regarding directories not being writable should disappear.

If no other errors are displayed, you can begin the XenForo installation process. In the early steps, you will be asked to provide details about your database server. If you do not know what values to use here, you will need to contact your host to get the correct values.

Once the database configuration is verified, if possible, it will be written out to your server automatically. If this is not possible, you will need to download the generated configuration file and upload it manually.

Uploading the generated config file

If the configuration file could not be written automatically, you will see a button to download the file to your computer. Click this.

Open your FTP client and navigate to your XenForo root directory. Within this directory, you should see a sub-directory called src. Open that directory and upload the config.php file you just downloaded here. You can now continue with the installation.

To complete installation, follow the on-screen instructions until it completes. XenForo is now installed and you can begin configuring it.

Upgrading XenForo

Upgrading XenForo follows a very similar process to installation.

You may upgrade from any previous version to the latest version directly. You do not need to upgrade to interim versions first.

Warning

Before upgrading, it is strongly recommend that you backup your XenForo database and files. It is not possible to downgrade once you start the upgrade!

You may need to upgrade add-ons for them to be compatible with the new version. Contact the add-on authors for details.

Upgrading from XenForo 1

If you are upgrading from XenForo 1, there are some important things to keep in mind. This is a particularly significant upgrade.

  1. XenForo 1 add-ons are not compatible with XenForo 2. You will need to contact the add-on author to see if they have an updated version of any add-ons you use. If you do not intend to use an add-on any longer, if possible, we recommend uninstalling it before upgrading. Not doing so may leave orphaned data in your database.
  2. XenForo 1 styles are not compatible with XenForo 2. The upgrade will not maintain any style property or template modifications. These will need to be redone after upgrading.
  3. Any other custom integrations you had with XenForo 1 are unlikely to work with XenForo 2 without some amount of changes.

If possible, we strongly recommend that you perform a test upgrade of your site on a test installation before upgrading your production installation.

Important

It is vital that you backup your site before upgrading to XenForo 1. You cannot downgrade after the upgrade starts. The only method of downgrading will be to restore from a backup.

1. Downloading

To begin, you must first download the zip file that contains XenForo from the XenForo customer area.

Click the Download XenForo link next to the license for the site you are upgrading. Before downloading, ensure that the Download the upgrade package only option is selected.

Note

If you have multiple licenses, please ensure that you use the files associated with the correct license for each site. There may be differences in the downloads (such as branding removal being applied) that could lead to accidental licensing violations.

2. Uploading

On your computer, unzip the file that you downloaded in step 1. Within it, you will see an upload directory. You will be uploading the contents of this directory to your server (not the directory itself).

Connect to your server using your FTP client and navigate to your XenForo root directory (the directory you installed XenForo into). In this directory, you should see files such as admin.php and css.php.

Use your FTP client to upload the contents of the upload directory that was contained within the zip that you extracted earlier to the XenForo root directory on the server. Ensure that all files and sub-directories are uploaded. If done correctly, you will be overwriting a number of existing files; you should allow your FTP client to do this if it prompts you.

Important

When uploading files, it's very important that you "merge" files with what's on the server. Some FTP clients may simply replace the contents on the server with exactly the contents that your uploading. If this happens, some files and data may be lost.

This upload may take some time. Once the upload is complete, you must continue with the next step. Your site will be closed until this step is complete.

3. Upgrading

Direct your browser to the install directory under your XenForo root URL. For example, if your XenForo root URL was www.example.com/community/, you would direct your browser to www.example.com/community/install/. If you have the correct URL, you should see the XenForo installer.

You may be prompted to login with an administrator user name and password. From there, follow the on-screen instructions to complete the upgrade. Once complete, your site will automatically reopen.

Upgrades from XenForo 1

If you are upgrading from XenForo 1, you may need to save a new config file. You will be prompted to do this at the beginning of the upgrade process. If the new config file cannot be written out automatically, you must upload it into the src directory under your XenForo root directory.

4. Post-upgrade checks

When you upgrade XenForo, we will not automatically overwrite any template or phrase customizations you have made. You should check if there are any outdated entries here under Appearance > Outdated templates and Appearance > Outdated phrases. You can use the template merging tools to attempt to automatically incorporate the core changes into your customizations.

If you are using a third-party provided style or language, you may wish to see if they have a release that is designed for the version of XenForo you are now running.

Common upgrading problems

Attempting a fresh install instead of an upgrade

If after uploading the files and going to www.example.com/community/install/, you are taken to perform a fresh install, this indicates that the files have not been merged correctly when uploading. It is possible that files have been removed unexpectedly.

At a minimum, you need to create the internal_data/install-lock.php file. The contents do not matter. Once done, you can direct your browser to www.example.com/community/install/. If it still takes you to a fresh install, please contact support.

If your internal_data or data directories are missing or empty, then attachments and avatars may have been removed. We strongly recommend restoring them from a backup.

No upgrade found

If after uploading the files and going to www.example.com/community/install/, it reports no upgrade is found, then the files have not been uploaded to the correct location.

In many cases, this indicates that the upload directory itself has been uploaded, rather than the contents. You should ensure that what you are uploading overwrites existing files.