Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

User:Felix/Upgrading WordPress

Detailed instructions

Following are detailed instructions for upgrading WordPress to 4.8, from versions 1.5.x, 2.0.x, 2.1.x, or 2.2. For an overview of the update process, please refer to the section Quick upgrade above. If you encounter problems, please re-read the intructions and consult common installation problems. It is a good idea to read the complete instructions before starting, especially the notes for special cases at the end. If you're having problems, try the WordPress support forums. For these instructions, it is assumed that your blog's URL is http://example.com/wordpress/.

Please note that it is important for the success of the upgrade that you follow the instructions carefully and precisely. If you do not (e.g you do not back up your data), you should know who to blame. Also note that your blog is not available for visitors during the upgrading process or may be broken.

Step 1: Backup old data

Back up your database

All of your WordPress data, such as posts, users or categories are stored in a MySQL database. In case the upgrade process is not successful, you may have to restore this data, which is why you are backing it up now. To do so, either

  • Use a web front-end like phpMyAdmin to access your database and export data and structure to a file on your local computer.
  • Use an administration tool of your database to create a backup, e.g. from a Linux shell.

Refer to backing up your database for a detailed explanation of this process.

Back up WordPress files

To be able to go back to the previously installed version of WordPress, you create a back up of all installed files. To do so, either

  • Download a copy of all files in your WordPress folder (the one that corresponds to http://example.com/wordpress/) to your local computer, using an FTP program. Your WordPress folder may include a .htaccess file, which may not be shown by your FTP program. Enable the display of hidden files and be sure to download and save this file as well.
  • Create a .tar file directly on the server including the full WordPress folder from your server's Linux shell, e.g. with tar -cvf wordpress-backup.tar /path/to/wordpress-installation-folder. Move the newly created .tar-file to a secure location, outside the WordPress folder. You will be deleting contents of this folder later on.

Verify your backups

To ensure that the backups made are usable, you should verify their integrity. To do so, either

  • Browse through the downloaded files on your local computer and compare them with the ones on the server.
  • List the .tar file's contents with tar -tf wordpress-backup.tar and compare it with the WordPress installation folder.

In a later step, you will need to copy parts of this backup back to server, so make sure everything is alright.

Step 2: De-activate all plugins

Some plugins currently installed may not work with the new version you are about to install, so de-activate them during the upgrade. You'll re-activate them later. To de-activate your plugins

  1. Login to your WordPress administration panel at http://example.com/wordpress/wp-admin and browse to the Plugins page.
  2. Remember all your activated plugins on the Plugins page of the WordPress administration panel. Write them down or save a screenshot to your local computer.
  3. On the Plugins page click Deactivate All Plugins.

Step 3: Replace WordPress files

To install the new version of WordPress you will first remove all old files from the server and then copy the new version to the server. Removing of the old files is a security measure to make sure that no files from the old installation are kept on the server.

Remove old WordPress files

Before removing the old WordPress files, once again make sure that you have a valid backup. You will need to copy files from the backup back to your WordPress installation. In case you have made customisations to your WordPress installation, make sure that you are aware what changes you had made. You might later need to re-do these changes to the upgraded WordPress.

To remove the old WordPress files, either

  • Use your FTP programm to delete all files within your WordPress folder (the one that corresponds to http://example.com/wordpress/).
  • Use the server's Linux shell to remove all files within your WordPress folder. cd into the respective folder and use rm -r * to delete the folders contents. Note that this command can delete your whole server's files if issued incorrectly.

Verify that the folder is empty.

Copy the new WordPress files to your server

The new WordPress files now need to be copied to your server. The files are available from the WordPress download page. To install the new files, either

  • Download the .zip file to your local computer, extract it to a new folder and upload its contents to your server's WordPress installation folder via FTP. Consult uploading WordPress if you need details.
  • Download the .tar.gz file directly to your server, e.g. using wget http://wordpress.org/latest.tar.gz<code>, extract it with <code>tar -xvfz latest.tar.gz and copy the files to your WordPress folder.

Re-add customised files from your backup

Since you had deleted all files, all your customisations are have been removed from the server. You will need to re-add some of the files from the backup into your WordPress folder to re-enable them. Use your FTP program or a Linux shell to do so.

What files exactly you need to re-add depends on your customisations, however here is a list of files valid for most cases. Copy the following files from your backup to your WordPress folder on the server:

  • /wp-config.php file,
  • /.htaccess file (if present)
  • wp-images folder
  • wp-includes/languages/ folder in case you were using a language file
  • folders and files from the /wp-content folder, in case you had custom content, plugins, themes or other customisations in this folder. The new WordPress version may include newer versions of these plugins or themes. If this is the case and you had made custom changes to the previous version, consider re-doing them in the newer version's files.

Step 4: Upgrade your installation

After the new files have been added to the server, other upgrades, e.g. to the database, might be necessary. WordPress provides an upgrade program that does the work for you. To run the programm

  1. Access http://example.com/wordpress/wp-admin/upgrade.php. If WordPress is installed in the root folder of your server, access the program at http://example.com/wp-admin/upgrade.php instead.
  2. Follow the instructions of the program.

Step 5: Update permalinks and .htaccess

To do so

  1. Login to your WordPress administration panel at http://example.com/wordpress/wp-admin and browse to the Plugins page.
  2. Update your permalink structure on the Options | Permalinks page.
  3. If necessary place the rules in your .htaccess file. See using permalinks for details.

Step 6: Re-activate plugins

You will now check whether the old plugins still work with the upgraded WordPress installation. To do so:

  1. Login to your WordPress administration panel at http://example.com/wordpress/wp-admin and browse to the Plugins page.
  2. Re-active the first plugins from the list you had created earlier by clicking Activate.
  3. Check your blog at http://example.com/wordpress/. If something looks wrong, deactivate the respective plugin and contact the author for an update.
  4. Repeat steps 2 and 3 for all other plugins on your list.

Step 7: Review what has changed in WordPress

Please review these resources to see what's new in the upgraded WordPress

Your WordPress installation is successfully upgraded.

Notes for special cases

  • Fantastico upgrades: When using the Fantastico upgrade process to upgrade from a pre-Version 2.2, Fantastico will use the wp-config-sample.php file to regenerate a new wp-config.php file. By doing this, two new values, DB_CHARSET and DB_COLLATE, are placed into the wp-config.php file. Those lines should be deleted from your wp-config.php if you are upgrading from a pre-Version 2.2 (like 2.0.10 or 2.1.3) to Version 2.2.1. A detailed explanation about DB_CHARSET and DB_COLLATE can be found in Editing wp-config.php.