WordPress Manual Upgrade for Experts

Jump to navigation Jump to search

There so many websites detailing how to manually upgrade a WordPress Site. The vast majority of them seem to be done by people with very little experience with all of the technologies behind WordPress like Linux (CentOS, Ubunto, etc.), PHP, Apache (Nginx, IIS, or other web servers), mySQL (MariaDB, SQL Server, etc.), and others. I mean no offense to them as they are talented in their own right and just trying to help. But it did make me think writing something about a simpler (and safer) way to upgrade a WordPress installation by leveraging more technically adept techniques. So I did.

It also brings up the question, "Why upgrade manually?" For me it was born of a desire to stay within the 4.X.Y series I was using instead of the 5.X.Y version offered as there is nothing in the 5 series the 4 series doesn't already provide for me on this particular site. There is a method to change the automatic upgrade method to ignore major version upgrades and only install minor versions (Major#.Medium#.Minor#), but after testing I determined it did not affect the manually triggered upgrade button.

Anyway, onto the detailed steps that leverage the command line and phpMySQL. The information also assumes one has command line access to a web server.


First of all BACK EVERYTHING UP!!! Assume the upgrade will mess something up and make a backup so you have a functional version to fall back on. For WordPress, that consists of two items: The website files and the database.

Website Files

Move the website files to another version (no need to copy, you'll understand, explained below);

mv WebSiteDirectory WebSiteDirectory.WorkingVersionX.Y.Z

...The original files will then be used to copy into the directory with the upgrade version, covered a few steps later.

The above is the quickest way to preserve a functional version of the website files (the MV command does not change permissions).

The next step isn't necessary, but if you want to make a copy of the website files and test those copied files for functionality and peace of mind, use the below command;

cp -ax WebSiteDirectory.WorkingVersion.X.Y.Z WebSiteDirectory

The WebSiteDirectory will need to be erased before copying the new updated WordPress files.
-a = -dpR = Preserve Symbolic Links and Recursive
-x = Exclude mount points, and thankfully this switch applies to several commands so it isn't documented in the MAN page for cp.

When testing the functionality of the site, it should be completely functional since the above command copies all files and directories (sub-directories too), retains permissions, retains symbolic links, IE makes an exact duplicate. If you do choose to make a copy, you'll need to delete it or move it so the original directory name can be used for the upgrade files.


For the database, use the mySQL (MariaDB, etc.) command line or phpMyAdmin. phpMyAdmin makes it much easier. Select the database in the left pane, Export Tab, "Simple" Radio Button, Go Button, save it to a file, done.

Other Thoughts

Most of the people that have documented how to do a manual upgrade of WordPress also stress the importance of backing up. Their methods won't work if the WordPress upgrade hoses the site for some reason. IE, if one uses a plugin to backup a WordPress site, an upgrade is done which hoses the site, how does one restore a backup with a plugin if the site doesn't work? Bit of an issue there, so instead why not get down to basics and uses some basic commands as explained here. The bottom line is that if one is doing some major stuff like an upgrade, don't rely on a plugin to restore things.


  • Download whichever version of WordPress you need / want from here (Minor version upgrades are the safest, IE 4.9.13 to 4.9.16): https://wordpress.org/download/releases/
  • Extract the files (if downloading a TAR version)


  • Move or copy the extracted files to a directory of the same name as the original web server directory (IE, after the above MV command when backing up the WordPress Site, the original Directory containing the site should not exist (or at least be empty)): mv Source Destination
tar -xf WhatEverFileName
mv WhatEverFileName NewFileName (to rename from the default WordPress Directory name)


tar -xvzf wordpress-w.x.yz.tar.gz -C /var/www/html/WhatEverDirectory (Don't worry about making a mess with a lot of files as the TAR File's first item is a Directory, as it should be)
  • Set the proper ownership and file permissions on the new files (the below example is for Apache on CentOS)
chown -R apache:apache /var/www/html/WebSiteDirectory 
find /var/www/html/WebSiteDirectory -type d -exec chmod 755 {} \;                      
find /var/www/html/WebSiteDirectory -type f -exec chmod 644 {} \;
  • Copy the working version of the WordPress website files into the new directory (The below command will not overwrite any of the new files and will also preserve all permissions from the "original / working" WordPress version. The end result is a directory with upgraded WordPress Files and all of the additional or custom stuff from the original site
cp -R -n -v -a -x /var/www/html/WebSiteDirectory.WorkingVersion/* /var/www/html/WebSiteDirectory

Don't forget the ASTERISK on the end of the Source.
Flags can be combined, IE -Rnvax, but are shown separately for clarity.
  • Make sure the original wp-config.php file is in the upgrade directory (The "original / working" version of the file should be copied with the above CP command as it does not typically exist in a newly extracted version of WordPress (it's generated))
  • Also remember a LOT of extensions make use of an .htaccess file (with Apache and other web servers) to modify the behavior of a WordPress site, so make sure the .htaccess file from the original version of that file is copied into the upgrade directory (it is a hidden file, so double check that). And after it was promptly forgotten by the author of this article, looked it up and found this reference too: https://tompai.pro/wordpress/solved-404-on-posts-and-pages-after-wordpress-update-to-4-9-8/ (it applies to other versions than the one noted in that article).


A good strategy for upgrading plugins is to make a manual copy of their physical directory (see command below), then use the GUI to upgrade the plugin. If everything works, great, if not, go back to the original version

cp -ax WhatEverExtension WhatEverExtension.BackUp


The website database may also need to be updated. Navigate to: https://www.riseofthesaltonsea.com/wp-admin/upgrade.php and it will prompt to update the database if necessary.

Final Thoughts

Depending on the complexity and customization of the WordPress Site, there may be complications. For me, there were two plugins that didn't function at 100%. You'll probably have some of your own unique issues too. The first best solution after upgrading WordPress is to update extensions too. Make a copy of your upgraded WordPress site in case any extension upgrades mess things up.

Magic Zoom

A great plugin that I really like, called Magic Zoom, which provides a zoom window like a magnifying glass to enlarge images had an 'image cache issue' that I was able to fix with a CHOWN command.

Image Map Pro

Image Map Pro, a plugin that allows custom regions to be defined on an image that produce a popup word balloon also wasn't functioning. After some quick troubleshooting I determined it was related to images that had been uploaded before the site had been converted to use HTTPS. The fix was fairly simple: Re-select the same image while connected via HTTPS.