Pretty Permalinks Checklist


This is a tutorial for people who are trying to get pretty permalinks to work on their WordPress site.

I assume the following:

  • You’re using a LAMP stack with WordPress 3.6 or higher
  • You have root access to the server on which your site is hosted
  • You have basic Unix skills (ie. you can use the cd command, and know how to open a text editor such as nano or vim)

Preamble

I have discovered through my extensive, frustration-laden, Google-aided quest that many, many people have issues with Pretty Permalinks. If you’re not already an Apache expert, it can be tricky to find and decipher the information you need to get permalinks up and working on your shiny new WordPress site. I’ve compiled the most common problems and their respective solutions here; I’ve also provided some links to further context/explanation for those who would like to understand what’s going on.

I’m going to assume you’ve already tried to change your permalinks structure via the WP control panel, and that you don’t need any further instruction on how permalinks work in general.

The official documentation lists the following requirements for pretty permalinks to work with Apache:

  1. An .htaccess file with appropriate rewrite rules
  2. Apache’s mod_rewrite module is installed
  3. FileInfo directives are allowed
  4. The FollowSymLinks option is enabled

Now we’re going to go through each of these requirements and verify that you meet them.

Requirement #1: an .htaccess file with appropriate rewrite rules

When you go from the default WordPress permalink structure to pretty permalinks, you’ll need to add some “rules” to your .htaccess file.

First, let’s check that you have an .htaccess file to work with. It should be in the same directory as WordPress’s index.php file, which is commonly found in /var/www/. If you don’t have one, create one (eg. echo "" > .htaccess).

Next, open up your .htaccess file. You’ll want the following code snippet to be present somewhere in that file:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.php$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.php [L]
</IfModule>

This is what WordPress suggests when you try to change the permalinks structure to anything but the default. It seems to be the same no matter what particular permalinks structure you choose. But if you want to be sure that you’ve got the correct rules, I recommend copy/pasting from WordPress’s suggestion in your dashboard.

Requirement #2: mod_rewrite module is installed

To check whether mod_rewrite is installed, try the command a2enmod rewrite.

If you get a message saying something like “Enabling mod rewrite”, it means that mod_rewrite was not formerly enabled, but now it is. Great! If the message says it’s already enabled, then you’re already good to go.

After you enable mod_rewrite, make sure to restart Apache using service apache2 restart.

(Credit for this tip goes to Marco Ceppi. You might also be interested in the official documentation for mod_rewrite.)

The WordPress documentation is pretty useful in outlining what needs to be done here. It might also be good to peek at the Apache documentation for the AllowOverride directive. I’ll just outline the actions you need to take. Requirements 3 and 4 can be satisfied by doing essentially the same thing, so I’ll deal with them both at once.

First, navigate to your Apache configuration settings. Try, for example, /etc/apache2/sites-enabled/000-default (or look in the folder /etc/apache2/sites-enabled/ and choose the appropriate file).

Look at the file. If your .htaccess file is located in /var/www/, then you’ll want to pay attention to the <Directory /var/www/> instructions (ignore anything else you see in that file). Make sure to enable the FollowSymLinks option and to add AllowOverride FileInfo as well. This means your <Directory /var/www/> section will look something like this:

<Directory /var/www/>
    Options FollowSymLinks
    AllowOverride FileInfo
</Directory>

While you’re looking at this file, please note:

  • If the <Directory /var/www/> section doesn’t exist, add it.
  • You can have several options in one line, eg. Options Indexes FollowSymLinks MultiViews
  • You might prefer to use AllowOverride All. I recommend reading the Apache documentation before taking this route.
  • After you’ve made the changes, be sure to restart your server (service apache2 restart).

That’s it!

If you’ve checked all of the items on this list, pretty permalinks should be good to go. Make sure you refresh your WordPress site before investigating your changes. Everything should work as intended, and now you can even change the permalinks structure within the WP dashboard without going through all this hassle again.

Good luck!

By the way, in your Googling you might have come across issues dealing with .htaccess permissions, which I haven’t yet addressed in this post…

Q: Do I need to give WordPress write permissions to my .htaccess file?

A: No, not really. This option is probably only desirable if you have an existing .htaccess file and don’t want to edit it yourself (laziness?), but I honestly can’t see any pressing reason to mess around with .htaccess permissions. In general, 644 is the recommended permissions setting for .htaccess files.