Fix Drupal 8 'Clean URLs' problems

Last updated on
11 May 2017

On this page:

In Drupal 8, clean URLS are enabled by default and can't be disabled. However, a rewrite module must be installed on your web server.

There are further instructions on Configuring Clean URLs for various systems such as apache, nginx, wamp, xampp and IIS.

Server configuration for Clean URLs

You can read more about other web server requirements

Server configuration for Clean URLs on a dedicated server, with httpd.conf

Enabling clean URLs on a dedicated server involves these steps:

  1. Enable mod_rewrite for Apache. You can talk to your web host or consult the Apache documentation for mod_rewrite to get more information on how to do this. At a minimum, this will involve making sure that mod_rewrite is enabled for your installation of Apache.

    To test if mod_rewrite is available in Apache2, you can type the following at a command prompt, to list all installed Apache modules:

    apache2ctl -M 

    On some systems this command may be:

    apachectl -M 

    In the output, check to see if the rewrite_module is included in the list of modules.

    If the rewrite module is not in the list, it will have to be either compiled-in or made available as a loadable module. Generally speaking, you can tell Apache to load the module by including

    
    
    LoadModule rewrite_module modules/mod_rewrite.so AddModule mod_rewrite.c 

    in your Apache configuration file (see below for information on the configuration file). Be sure to uncomment AddModule mod_rewrite.c, if it is in your configuration file but has been commented out. The following may work to enable the module without editing any files:

    
    
    a2enmod rewrite 

    Note that these approaches may not work for all combinations of operating system and Apache server -- consult the Apache documentation that came with your Apache software for the correct syntax.

    Remember to restart Apache for the new configuration to take effect.

  2. The next step is to locate the appropriate Apache configuration file for your site. Depending on your server configuration, the appropriate Apache configuration file could be httpd.conf, a virtual-host-specific file (vhost.conf), a specific site file (e.g. "default"), or apache2.conf. They are usually located in /etc/httpd/conf, /etc/apache2, or a sub-directory; if not, try the command:
    
    
    find /etc -name httpd* or find /etc -name apache2* 

    to find the file if it is located elsewhere in your file system.

    If you do not have write permissions to these files, and Clean URLs are not working out-of-the-box for you, you may have to ask your systems administrator or hosting provider for help. You may still be able to read these configuration files to troubleshoot a little however.

  3. The next step is to copy or include the Drupal-specific settings directly into your configuration file. There are instructions here for how to include the Drupal directives in your configuration file. Consult the .htaccess file in Drupal for examples of rules, such as the following for Drupal 8:
    
    
    RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_URI} !=/favicon.ico RewriteRule ^ index.php [L] 

    Or this example on a Debian 8 + Apache2 + ISPConfig, using wildcard to match all sites installed:

    
    
    <Directory /var/www/clients/*/*/web/> RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] </Directory> 

    Make sure that you are looking at the .htaccess file for your major version of Drupal (i.e., 8.x.

Note: If you do not want to put the rewrite rules in your Apache configuration file, you can still simply use the Drupal .htaccess file (as you would if you were on shared hosting). You will need to have the Allow Override directive set in your Apache configuration file (this will allow local .htaccess overrides on your site):


AllowOverride All AccessFileName .htaccess 

Read Behind the scenes with Apache's .htaccess for a thorough review of .htaccess. You may also find it helpful to view samples of Apache 2 AllowOverride directives.

Note Regarding MultiViews: Apache supports a feature called "MultiViews" (more generally: "Content Negotiation"), which allows navigation to your pages without the need for file extensions. For instance, if you had a file called "evaluation.txt", a MultiViews-enabled site could access this file with the URL "example.com/evaluation". While MultiViews can be a handy feature when used knowingly, it can cause problems when Drupal's Clean URLs are enabled. Unless you know what you're doing, you should not use MultiViews if you plan to use the Clean URLs feature of Drupal. However, MultiViews is not enabled in a default Apache installation, so it is likely that this note will not apply. Consult the Apache documentation for further information about MultiViews.

Server configuration for Clean URLs on a shared server, with .htaccess

The standard Drupal installation contains a sample .htaccess file which should be sufficient to get Clean URLs running. It is easy to miss copying this file, because of the leading "dot". So before trying to enable Clean URLs, make sure this file exists in your Drupal installation.

To check for this in terminal, use ls -a to make sure the "dot" files are also listed.

If you have this file installed, but Clean URLs still do not work, you can try some of the troubleshooting suggestions below. If you still cannot get Clean URLs to work, contact your hosting provider.

Fixing problems

Check if .htaccess is being used

Apache needs to be explicitly told to respect the instructions in your sites .htaccess file. This is off by default, though most hosts will have turned it on. That is what the AllowOverride All directive above does - it makes .htaccess start working.

To check if your host is reading the .htaccess file, you can (temporarily) add some garbage string to the file in an attempt to break it. Your site should immediately start returning a "500 Server Error" when you load a page from that directory due to this misconfiguration. (Remove the garbage string immediately.)

If you do this, and your site does not break - then .htaccess is being ignored and you will not be able to use clean URLs until you get support from your hosts, or enable it in httpd.conf as described above. Some hosts allow you to enable this option through their site management control panel, so look there first.

RewriteBase setting

The main configuration option which may need to be changed for your site is the RewriteBase. This can be specified in the Drupal .htaccess file or in the httpd.conf file, depending on where you are putting the Drupal rewrite directives (see above). By default, the RewriteBase setting is commented out of the Drupal .htaccess file, and that works well for many configurations.

If you are having trouble getting Clean URLs to work, you may need to change this setting. For example, if your Apache DocumentRoot is /var/www/ (i.e., /var/www/index.html is what is displayed when you point your browser at http://www.example.com/) and your Drupal installation is installed in the subdirectory /var/www/mysite/, then the RewriteBase could be set to


RewriteBase /mysite 

and that might help. In some configurations, setting


RewriteBase / 

will allow clean URLs to work.

$base_url

You may need to manually set the $base_url variable in the settings.php file if not already set. It's currently known that servers running FastCGI can run into problems if the $base_url variable is left commented out (see http://bugs.php.net/bug.php?id=19656).

Multi-site

RewriteBase works when your Drupal installation serves only one site, or when all the sites it serves are in the same subdirectory of their domains. For example,


RewriteBase / 

will work for the following sites:

http://www.example.com/
http://www.example2.com/
http://www.example3.com/


RewriteBase /mysite 

will work for the following sites:

http://www.example.com/mysite
http://www.example2.com/mysite
http://www.example3.com/mysite

However, if your sites are in different subdirectories, RewriteBase will not work. You will need to create a special rule for each subdirectory. For example, your Drupal installation may serve the following sites:

http://www.example.com/
http://www.example.com/mysite

In order to enable clean URLs for both sites, you will need to add


RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_URI} ^/mysite/ RewriteRule ^ /mysite/index.php [L] 

before the existing rewrite rules.

Location of index.php

For some server configurations, another change to the Drupal .htaccess file may be necessary. Find a line that looks like this, near the end of your Drupal .htaccess file:


RewriteRule ^ index.php [L] 

You may need to replace index.php with the URL path to your Drupal installation's index.php file (only the part after the base URL). For instance, if your site's home page URL is http://example.com/subdir/, you might need to use /subdir/index.php instead of index.php. If your site's home page URL is http://example.com/, you might need to use /index.php instead of index.php. This is necessary on some, but not all server configurations.

Create Even Cleaner URLs with the Path Module

Using Clean URLs will cause Drupal to generate URLs in the form "http://www.example.com/node/83." In order to change the 'node/##' portion of the URL to something more like 'news/june-1st-news' a site will need the Path module enabled. See the Path module handbook page for more information on using the path module.