Ultimate Guide to htaccess and mod_rewrite

by Patrick Altoft on July 14, 2007

Often described as “voodoo” by frustrated webmasters the use of mod_rewrite and htaccess files is one of the more advanced tasks a web developer has to face.

The good news is that unless you are looking for really advanced solutions you don’t have to fully understand how they work to use them on your website. Most of the htaccess and mod_rewrite tips on this page can simply be cut and pasted into a text file and uploaded to your server.

Over the last few years I’ve given the same htaccess tips to hundreds of webmasters so I decided to create a page with all the common uses.

htaccess is a configuration file that controls Apache web servers, mod_rewrite is a rewrite engine used by web servers to modify urls before they load.

The htaccess file is a text file called .htaccess – htaccess is the file extension, there is no filename. Normally it resides in the main root directory on your server but you can also create individual htaccess files for different directories on your site.

Canonicalization

The easiest htaccess trick is to make sure that your site doesn’t have any canonicalization issues on the homepage.

A lot of websites suffer from poor search engine rankings by having a number of different versions of the homepage, for example:

http://www.yoursite.com

http://yoursite.com

http://www.yoursite.com/index.html

http://yoursite.com/index.html

These pages are all seen as different urls, despite them having exactly the same content in most cases. Google has got better at deciding which version to use over the past 12 months but you can still run into problems.

To solve this issue simply add the following to your htaccess file:

Options +FollowSymLinks
RewriteEngine on
RewriteCond %{HTTP_HOST} ^yoursite.com
RewriteRule (.*) http://www.yoursite.com/$1 [R=301,L]
RewriteCond %{THE_REQUEST} ^[A-Z]{3,9}\ /index\.html\ HTTP/
RewriteRule ^index\.html$ http://www.yoursite.com/ [R=301,L]

This will redirect all versions to http://www.yoursite.com

Changing html files to php

Sometimes you might have a static html website and need to use php code on the html pages. Rather than redirecting all your html pages to the equivalent php versions you simply need to tell your server to parse html files as if they were php.


AddHandler application/x-httpd-php .html

This works with any files so if you want to create dynamic xml or asp files that behave like php files you simply edit the code as required:


AddHandler application/x-httpd-php .xml
AddHandler application/x-httpd-php .asp

Error pages

Custom error pages can be set up in cpanel fairly easily, if you want to create a custom error page in htaccess instead use this line:


ErrorDocument 404 http://www.yoursite.com/404.php

Directory Indexes

To avoid Google indexing your directory indexes you might need to specify an index page for your directories. This is not required on some servers.


DirectoryIndex index.php3

My preference is to redirect the directory index page to either the homepage or another suitable page. For example www.yoursite.com/images/ can normally be redirected to www.yoursite.com and www.yoursite.com/forum/ can normally be redirected to www.yoursite.com/forum/index.php

Redirecting pages

A nice simple use of htaccess is to redirect one page to another:


redirect 301 /old-page.php http://www.yoursite.com/new-page.php

Sending your feed to Feedburner

If you want to switch your feed to the Feedburner service you will need to redirect your current feed to the new http://feeds.feedburner.com/yourfeed location.

The redirect needs to apply to all users except the Feedburner spider:


RewriteCond %{HTTP_USER_AGENT} !FeedBurner
RewriteRule ^your-feed\.xml$ http://feeds.feedburner.com/your-feed [R,L]

Advanced hotlink protection

If you want to block other websites from hotlinking your images, but allow indexing of your images in the Google, Yahoo and MSN image search engines, you should use the code below:


RewriteEngine on
RewriteCond %{HTTP_REFERER} .
RewriteCond %{HTTP_REFERER} !^http://([^.]+\.)?yoursite\. [NC]
RewriteCond %{HTTP_REFERER} !google\. [NC]
RewriteCond %{HTTP_REFERER} !search\?q=cache [NC]
RewriteCond %{HTTP_REFERER} !msn\. [NC]
RewriteCond %{HTTP_REFERER} !yahoo\. [NC]
RewriteCond %{REQUEST_URI} !^/hotlinker\.gif$
RewriteRule \.(gif|jpg|png)$ /hotlinker.gif [NC,L]

The hotlinker.gif image is a custom image that you have created. I suggest using something like “This image was hotlinked from www.yoursite.com” and your logo.

My personal preference is to allow hotlinking but to implement a solution to make use of Google Images and hotlinkers to build links to your site.

Create beautiful url’s with mod_rewrite

The Apache rewrite engine is mainly used to turn dynamic url’s such as www.yoursite.com/product.php?id=123 into static and user friendly url’s such as www.yoursite.com/product/123


RewriteEngine on
RewriteRule ^product/([^/\.]+)/?$ product.php?id=$1 [L]

Another example, rewrite from:

www.yoursite.com/script.php?product=123 to www.yoursite.com/cat/product/123/


RewriteRule cat/(.*)/(.*)/$ /script.php?$1=$2

Removing query strings

Some websites like to link to you by adding an query string, for example I could link to www.yoursite.com/index.php?source=blogstorm just so you know where your traffic came from. This creates duplicate content issue for your site so you really need to redirect back to your homepage:


RewriteCond %{QUERY_STRING} ^source= RewriteRule (.*) /$1? [R=301,L]

Further reading:


If you have any questions please post in the comments.

Patrick Altoft is Director of Search at Leeds based digital & SEO agency Branded3. Patrick also runs Blogstorm.

You can get our blog posts delivered for free by email every day - simply add your email address to the box below or alternatively grab the RSS feed.

Read some similar posts

{ 38 comments… read them below or add one }

Richie 15 Jul 2007 at 5:06 am

You’ve some great tips there,thanks Patrick!

Free SMS Andy 16 Jul 2007 at 3:14 am

Fantastic guide! You’ve made everything seem so simple. As you mentioned, htaccess has always been ‘voodoo’ for me

othello 27 Jul 2007 at 6:05 am

simple, elegant but rocks!

dew 27 Jul 2007 at 1:28 pm

eh, it’s still pretty voodoo to me, even after reading lots of places, i still don’t seem to get it.

I’m trying to take something like
site.com/pages/page1.php
but make it really go to:
site.com/pages/index.php?id=1

and I have about 10 of those pages, each with different names like page2.php and page3.php. so I would need a rule for each one i think, but I just can’t seem to get it to work how I need… any suggestions or help?

TE 08 Aug 2007 at 8:21 pm

Excellent advice – thanks.

One thing I cant fathom tho:

I have http://www.example.eu pointing to the same name servers as my main site at http://www.example.com

How would I write into the htaccess for anything coming to the .eu site to be rewritten to the .com site so as to avoid dupe issues?

Thanks

youngus 09 Aug 2007 at 1:19 pm

thnx for all these. Smile have a little problem with my site. The situation is: I have LoadModule rewrite_module modules/mod_rewrite.so
in my httpd.conf,
the DocumentRoot is “/var/www/html”, and my site is under the html directory, that means /var/www/html/mysite/,
I put .htaccess file these directives:
php_value error_reporting 7
RewriteEngine On
RewriteBase /
Options +FollowSymlinks
RewriteRule ^([0-9]+)/(.*)?$ /index.php?module=item&action=show_item_decr&item_id=$1

but it seems that it doesn’t work ! it gives me a 404 page, and even if I put one of your directives it doesn’t work , can you help please ! is there anything I have to add ! thnx !

Benjamin 30 Aug 2007 at 3:48 am

When I use
RewriteCond %{QUERY_STRING} ^source= RewriteRule (.*) /$1? [R=301,L]

I get a 500 server error.

Am I not using it right?

Wouter 05 Dec 2007 at 2:55 am

Thanks for the useful tips!

David Airey 19 Jan 2008 at 1:11 am

Cheers Patrick. I’ll mention this article on my latest blog post.

Dave 26 Jan 2008 at 9:44 am

dew: eh, it’s still pretty voodoo to me, even after reading lots of places, i still don’t seem to get it.

Apache mod_rewrite IS voodoo. That’s why it seems like voodoo to you.

It even says so in the official documentation. (Although they removed that quote from the 2.0 docs, mod_rewrite is still the same, and still voodoo.)

Josh 21 Apr 2008 at 4:15 am

Very good tips. I spent one whole morning on .htaccess and got it done only when I found this article.

AskApache 25 Apr 2008 at 12:50 am

You might enjoy checking out the .htaccess guides here too.

Nice and simple tutorial, thanks!

Jon 22 May 2008 at 10:53 am

Thanks for the tutorial, Patrick

I used it to redirect an old static site to a Wordpress site. I discovered some extra bits along the way that might be useful -

- If you’re using WP permalinks, WP adds some lines to htaccess. make sure you put additional stuff outside the code block that WP adds. Otherwise it may get overwritten next time WP writes to htaccess.

- Put your redirects before the code that WP adds, so that they are processed before control is passed to WP

- If there are spaces in the old URLs, put quotes around them. Eg.
redirect 301 "/old page.htm" http://www.mysite.com/newpage

(NB. there is a WP plugin called “Redirection” but I wanted to learn about htaccess, and keep my list of plugins as short as possible!)

Thanks for a great site, good to read a UK perpsective on SEO stuff!

Cheers, Jon

Ian Wortley 14 Jul 2008 at 10:20 pm

Wow… that’s a great artical. You have no idea how many different versions of rewrites I have crawled through…. none of them worked…. until yours. I am more than grateful!

I have a question though. Windows live has indexed http://www.mysite.ie/?

How or why I don’t know but I’d like to get rid of it. I have not got my head around regex yet and can’t work it out… I ended up with a loop when I tried to modify your QUERY_STRING source= (which was absolutely ideal for getting rid of my index.php?url=home problem.. Thanks again).

While I owe you big time already I’d appreciate any help you could offer with this… be it a solution or where to look for one… I’m stumped!

You have my site address and email address should you need them.

Thanks again for your brilliant page.
Ian.

Patrick Altoft 15 Jul 2008 at 8:59 am
Find me on Twitter

I suggest just redirecting it in your domain registrar control panel rather than using htaccess.

More comments from Patrick Altoft
ganesan 28 Jul 2008 at 1:33 pm

hi mr Patrick Altoft,
Thank you i am new to htaccess. Very help ful for your wonderful tips

Craig Mullins 05 Aug 2008 at 12:50 am

Great info. One issue with the Canonicalization script. The url’s and directory’s should end with a trailing slash.

http://www.yoursite.com/
http://www.yoursite.com/directory/

It will save an extra query on your web server and make it just a tad faster.

Let me know if you modify that, so I can ad it to my htaccess file.

redditch 09 Jan 2009 at 1:37 pm

Thanks for the tips I’m still struggling with some rewriting but i’m certainly getting better!

wa2n 21 Feb 2009 at 2:32 pm

good article

Dat Hoang 12 Apr 2009 at 3:54 pm

Very useful tutorial! It’s easy to learn how to make clean and nice urls. Thank you for your tutorial, Patrick Altoft.

Luke Fretwell 20 May 2009 at 10:43 pm

I am trying to optimise my football team’s website. The player profile pages url is:
/players.php?player=lukefretwell
I managed to write the a rule so if you type /player-lukefretwell you will go to /players.php?player=lukefretwell while keeping /player-lukefretwell.
But I also want it so that if you type /players.php?player=lukefretwell the address bar changes to /player-lukefretwell and still go to /players.php?player=lukefretwell

My reason for wanting to do this is that I am worried that google will index both types of url, then this would dilute the pages and also flag up duplicate content.

Am I wrong in understanding that the two can both be indexed. If I am right to worry is it possible to do a rule to just rewrite what is seen in the address bar?

Patrick Altoft 21 May 2009 at 7:22 am
Find me on Twitter

Luke you do need to write a rule to redirect. If you can’t figure it out in htaccess then create a copy of players.php and call it players2.php and use this as the script to generate your /player-lukefretwell pages. Now change your players.php to use a php redirect at the top which points to /player-$player

More comments from Patrick Altoft
Thecastex 19 Jun 2009 at 3:01 am

Nice tutorial. Very simple for me, thanks…

richardbaxterseo 29 Jun 2009 at 9:45 am
Find me on StumbleUpon | Twitter

Solid write up and extremely useful. Thanks Patrick!

More comments from richardbaxterseo
pjbyrnes 20 Jul 2009 at 12:59 am

I have been banging my head against the wall to do what I believe is a simple task. My client need me to simplify a url:
FROM:
http://hhhh.com/saccny/index.php?pageRef=chairmanandvicechairmen

TO:
http://hhhh/saccny/Board_of_Directors

I don’t need it to automate for the entire site and I cannot afford to have the php code rewritten. I am happy to add a string to the .htaccess for each url I need changed. Is this difficult to do? It is not a redirect because http://hhhh/saccny/Board_of_Directors does not really exist.

sandiegowebdesigner 28 Jul 2009 at 1:01 am
Find me on Twitter

I’ve also read that google treats domains with a trailing slash (ie, http://domain.com/ and http://domain.com ) as two different websites, as well as http://www.domain.com/ and http://www.domain.com WITHOUT the trailing slash,so there’s even more url bleeding?

More comments from sandiegowebdesigner
jeff 09 Sep 2009 at 7:09 pm

Hi there,

If I do a mod rewrite do I then need to do a 301 redirect to so there is no duplicate content?

Thanks in advance.

Jeff

TONY DUNG 12 Nov 2009 at 10:51 am

Help me to create file .HTACCESS for apache (php website) for
http://www.vietnamdhtravel.com
Thank you so much

Jintu 14 Nov 2009 at 9:59 pm

Thanks for making these so easy.

Paras 17 Dec 2009 at 8:51 am

Hi Patrick… After reading this and other articles on net I am able to
redirect pages http://www.asd.com/case/20-2040 to pages like http://www.asd.com/xyz.php
using
RewriteRule ^case/([0-9]{2})-([0-9]{4}) xyz.php [NC]

but what is happening is that it is not taking css .
Further more if I am using
RewriteRule ^case/([0-9]{2})-([0-9]{4}) http://www.asd.com/xyz.php [NC]
It works fine but the url in address bar changes…..

Can you solve my problem.thnx in advance

Ian Wortley 17 Dec 2009 at 10:20 am

Hi Paras, What is happening there is that your page is looking for the CSS in the wrong folder. You have redirected to a folder that is up a level. By changing the path of your CSS file to the root directory you should be able to fix it. This depends on the file structure of your hosting provider. Ask them for the path to your root directory.

Alternatively you could try adding ../ before your path. The two dots signify going up a level in the directory.

Hope that helps.

Ian.

hey guys 26 Apr 2010 at 10:00 am

if all of u wanna mod_rewrite url
u should change url internal link at ur php/script
then modif ur htaccess

suwun

Kerry Bullmore 14 Jun 2010 at 11:16 am

Hi Patrick
Surfing the web certainly comes up trumps from time to time. I only recently discovered the power of htaccess and the addition of nofollow code to help prevent loosing link juice. I appreciate the depth of your post.
Regards
Kerry

MMORPG Gamer 11 Jul 2010 at 6:35 pm

Thanks! I was looking for a good hotlink protection.

Andrew North 16 Jul 2010 at 4:01 pm

Hi Guys,
It still amazes me to this day just how much developers dislike working on mod_rewrites or htaccess files their is so much useful information regarding this stuff should make things straight forward.

Great post Patrick

Jason 17 Jul 2010 at 9:27 pm

I had to do this a couple of weeks ago while using FTP Core. This is the best way I have seen it explained for people yet. I am going to make a post on one of my sites linking back to this as there aren't a lot of people out there explaining it like you have. Thanks for the great info as always Pat.

Jeremy Owens 01 Aug 2010 at 9:49 pm

I still don't understand why people would want to stop hot linking images. Isn't that this some kind of exposure to your web? I mean, if people in the forum talk about image that we post and they also point the source, wouldn't be great?

Gaming SEO 07 Aug 2010 at 4:05 pm

If I'm understanding you correctly, I personally don't mind people using my images "if" given a link back. However I'm in online gaming industry which attracts dodgy webmasters who scrap your source code and hotlink to images.

These creeps give no recognition for the image, which can add up to gigs of bandwidth a month being stolen. It's unfortunate that honest webmasters these days have to protect their content, images and basically anything on their site from being scrapped.

Just as piece of free seo advice, if your site uses an rss/atom feed…only post extracts to it, don't post full text content. It makes it less attractive to scrappers.

{ 6 trackbacks }

How to stop image hotlinking and bandwidth theft | David Airey :: Graphic and Logo Designer
01.19.08 at 1:14 am
SEO Mod Rewrite | Search Engine Optimisation (SEO) Feed from Position Gold Ltd
09.30.08 at 9:07 am
Easy Clean URLs with Apache’s mod_rewrite « Junaid Bhura
09.04.09 at 11:56 am
5 Aspectos básicos de SEO a optimizar en tu blog | Bloguismo
01.14.10 at 9:30 am
Inhoud van aangepaste map browsen in een Wordpress website
04.13.10 at 2:25 am
MODE_REWRITE - TechFreekz
05.13.10 at 11:56 am

Leave a Comment (registration is optional)

Registration is free, takes about 5 seconds and is worth doing.

You can use these HTML tags and attributes:
<a href=""> <b> <blockquote> <code> <em> <i> <strike> <strong>