If you’ve ever managed a WordPress site, you might have run into an issue where plugins or themes couldn’t be installed, images couldn’t be uploaded to the media library, or files that you expected to be on the site just weren’t showing up properly.
At the heart of all these issues is the concept of file permissions, but if you’ve never managed a web server you might not be quite sure what file permissions are, how they work or how they get misconfigured in the first place.
In this article, we’ll take a look at everything you need to know about file permissions and how they work in WordPress.
We’ll examine some of the specific instances where you’re most likely to see file permission errors and investigate how you can diagnose these errors and debug them.
What are file permissions?
From the earliest multi-user computer system, file permissions have been needed to decide which users have access to which pieces of the filesystem.
For example, each user typically has a “home” folder, which they can access, but which other users on the system can not.
What allows this is a set of file permissions that fall into 3 categories:
- What permissions the owner has.
- What permissions the file group has.
- What permissions everyone has.
These permissions are usually expressed in one of two ways: as a number or as a string of characters. The file permissions that each of these numbers and characters represent are the same in both cases.
The way these permissions are set determines who can access a given file at any given time.
How are file permissions used in WordPress?
In most cases, the server that is running a WordPress site is running as a particular user.
Just like any user on the system, files owned by the web server user tend to be accessible to that user and thus accessible to the WordPress installation that the user is running.
This is important because for WordPress to run updates, allow users to upload media, install plugins and themes, and most everything that WordPress does to run, it needs permissions to access the various directories inside the WordPress installation.
If the system user that WordPress is running under doesn’t have access to write to the uploads directory, for example, anyone attempting to upload media inside the WordPress admin area will see an error message and not be able to add anything to the Media Library.
On the other hand, setting up permissions that are too open means that anyone could modify files inside your WordPress installation, which is a security risk as well.
That’s why it’s very important to set file permissions correctly. If you are using a managed host, these will likely already be configured for you.
Be careful of 777
If you run across a file permissions error and start looking around online for solutions, many tutorials will recommend setting the file permissions of one or more directories inside your WordPress install to “777 permissions”.
This is the most open set of permissions possible and means anyone can read or write anything inside that directory.
The thinking behind setting a problematic directory’s permissions to 777 is that once you do this, if your issue is resolved, then file permissions were the issue and you can start looking more deeply at which directories might have incorrect permissions set.
While this is fine for temporary debugging, leaving directories with this level of permissions long-term is a security risk. If you leave any of your directories set to these completely open permissions, then anyone who is familiar with how WordPress works and the directory structure could potentially get access to your files.
Setting your permissions to 777 and leaving them there is basically like getting locked out of your apartment, breaking the lock off the door, and leaving it like that.
While it does solve your problem at that moment, it also leaves you open to other security vulnerabilities. Leaving these file permissions open for more than just a brief debugging means that your WordPress site, and your web server in general, is more vulnerable to hacked and exploited plugins as well as the automated attacks that are run across wide swaths of the web.
Common errors due to file permissions
Now that we know a bit about how file permissions are used and how they work within WordPress specifically, let’s take a look at some of the errors you might see that are due to file permissions being set up incorrectly.
Themes, plugins, or WordPress core fail to install/update
Sometimes when you’re running updates or installing new themes or plugins you’ll run into an error where the plugin could not be installed or the update could not be completed.
In many cases, this is a file permissions issue and specifically, a mismatch between the web server user that is running WordPress and the web server user that has access to, and ownership of, the
wp-content directory. This often happens when you update files in the
wp-content directory via FTP.
In this case, the ownership of the directories you uploaded via FTP gets set to the FTP user, while the web server user that is running WordPress is different. When WordPress tries to install a new theme or plugin, the web server denies this attempt because WordPress doesn’t have ownership over the folder.
That means that WordPress doesn’t have the correct permissions to insert or change files inside the wp-content folder, which is why the installation or update fails.
Media uploads fail
Media uploads that consistently fail but don’t trigger the error messages stating that they’re too large or of an incorrect format might mean that you also have a file permissions error.
If the web server user that’s tied to WordPress doesn’t have permission to access either the
wp-content directory or the
uploads directory specifically, then uploaded media files will not be able to be transferred to the correct directory and the upload will be reported as failed.
Media files exist on the server, but 404 when accessed through the browser
Especially after restoring a WordPress site from a backup or migrating it between hosts, you may find that, even though media files are correctly uploaded to your site and present in your
wp-content/uploads directory, they are still throwing a 404 error when they’re attempting to be accessed in the browser.
When this happens, it usually means the operating system user that is running the web server doesn’t have permission to access the images on the server, and thus can’t serve them to the visitor’s browser.
Just like the problems and solutions above, you should check each directory, starting with
wp-content going down through
uploads and each of the monthly directories as well as the images themselves, and make sure the web server user has read permissions on all these folders and files so that the media can be properly displayed to visitors in their browser.
How to fix file common permission errors
The easiest way to fix common file permission errors is to make sure that the file permissions are set the way that WordPress expects them to be.
First, verify that the same web user that is running WordPress has ownership over the root directory where WordPress is being run (this is the directory where your wp-config.php file exists).
After that, make sure that all of the WordPress files in this directory, as well as the wp-content directory and all the directories underneath that are owned by that same user as well.
If you are using a web host that uses cPanel, you can change these permissions from right inside cPanel. However, if you have SSH access to your server and are running a Linux-based server (which most web servers are), then you might have to follow a slightly different method.
Other potential file permission errors
Outside of core WordPress and basic theme and plugin functionality, there are a couple of other places where you might run across file permissions-related errors as well.
Namely, some plugins use the filesystem of your WordPress site to do their work and if they can’t do the work they need within the file structure, you could see some weird errors pop up.
Often these are backup plugins (which sometimes store the backups within the
wp-contentdirectory) and caching plugins (which sometimes generate and store static caches inside the
If you start seeing errors with any of these sorts of plugins, the fix is the same as identified above. You need to make sure that the web server user that is running WordPress is the owner of, and has permissions to, your
wp-content directory so that files that your installed plugins need to store can be placed there.
What are the correct file permissions of WordPress
Even though each installation may be slightly different, there are general guidelines as to what file permissions should be for various types of files and folders in WordPress.
In general, per the WordPress guidelines, “It is best to lock down your file permissions as much as possible and to loosen those restrictions on the occasions that you need to allow write access, or to create specific folders with fewer restrictions for the purpose of doing things like uploading files.”
With that in mind, there are a few areas of the site that need various permissions setup. Most of the files within the WordPress root and deeper should be owned by your user account and writeable from that account, however, there are a few other places that need to be writable by the web server so that WordPress can make changes to these files.
uploads directories need to be writable by the web server, especially if you want to run automatic updates or use the theme editor from within WordPress.
If you do not wish to use these features, you can make things even a bit more secure by making these directories not writeable by the web server. This will allow your site to still function as normal without opening up the possibility of malicious changes being made to any of these files.
Despite not being something most WordPress site owners have to deal with, especially since the rise of managed hosting, file permissions can still produce some hard-to-debug errors.
However, if you know the signs and the common types of errors that have an underlying cause of file permissions being incorrectly set, you can speed up the process of getting your site back on track.
By knowing a bit about file permissions and how the operating system underneath your WordPress site operates, you’ll be able to solve any potential permissions errors more quickly and help others do the same!