Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

mod_rewrite And Friends

mod_rewrite is one of the most powerful, and least understood, of the modules that are provided with the Apache HTTP Server. It is frequently misused to do things that can be done so much better other ways.

Thousands of examples are posted daily on various websites, showing beginners how to do things with mod_rewrite, and, unfortunately, the vast majority of them are wrong in various ways, subtle or grevious, due to misunderstandings of how mod_rewrite works, or how regular expressions work.

This book is intended to help you understand mod_rewrite deeply, so that you know when and how to use it, as well as when not to use it, and what to use instead.

About This Book

The first incarnation of this book, [The Definitive Guide to Apache mod_rewrite](, was published in 2006. Since then, so much has changed that while that book is still useful, it’s far from complete.

In February of 2012, Apache httpd version 2.4 was released, with a huge number of enhancements and changes. Many of the things that people have been using mod_rewrite for now have better solutions. Meanwhile, mod_rewrite itself improved quite a bit, too, and can do many new things.

This book still focuses primarily on mod_rewrite, but will touch on many of the surrounding topics and modules.

That said, the scope of this book has expanded (since the earlier incarnation) to include not merely URL rewriting, but also methods for munging (modifying) content, and dynamic conditional configuration. In many cases, these techniques make mod_rewrite unnecessary, or, at least, provide easier alternatives, so they fit the scope of the book very well.

These techniques include mod_substitute, mod_proxy_html, the Define directive, the <If> container, mod_macro, and many more. Along the way, we’ll also discuss the various parts of URL mapping, the understanding of which allows you to avoid using these more complicated techniques.

How this book is organized

This book consists of 14 chapters. Depending on your level of existing expertise, some of them can be safely skipped.

Chapter 1 - Regular Expressions - This chapter gives an introduction to regular expressions, which are the language of mod_rewrite.

Chapter 2 - URL Mapping - URL rewriting is a portion of a larger topic called URL mapping - the process by which Apache httpd translates a requested URL into an actual resource that it will serve.

Chapter 3 - An introduction to mod_rewrite - covering some of the configuration directives that need to be set up before you start rewriting.

Chapter 4 - RewriteRule - The RewriteRule directive is the one you’ll be using most often. This chapter covers its syntax and usage.

Chapter 5 - Rewrite Logging - The rewrite log is a great debugging tool, and also a good way to learn about how mod_rewrite thinks about things.

Chapter 6 - RewriteRule flags - Flags modify the behavior of RewriteRule. They’ve been introduced in the previous chapter, but this chapter covers each flag in detail, with examples.

Chapter 7 - RewriteCond - RewriteCond allows you to put conditions on the running of a particular RewriteRule.

Chapter 8 - RewriteMap - The RewriteMap directive allows you to craft your own RewriteRule logic and lookup tables.

Chapter 9 - Proxying with mod_rewrite - RewriteRule’s `[P] flag lets you pass a request through a proxy. This chapter digs into that in greater detail.

Chapter 10 - Virtual hosts with mod_rewrite - Using RewriteRule to manage virtual hosts.

Chapter 11 - Access control with mod_rewrite - Using RewriteRule to control or restrict access to resources.

Chapter 12 - Configurable Configuration - New in version 2.4 of the web server is a class of directives that let you add intelligence and request-time decisions to the configuration. These techniques replace many of the things that people used to use mod_rewrite for.

Chapter 13 - Content Modification Modules - In this chapter, we discuss rewriting content sent to the client, which is not something that mod_rewrite does.

Chapter 14 - Recipes - Recipes, and detailed discussions of them, addressing common problems and solutions.

Other Sources of Wisdom

A brief word about the documentation. The official docs, at, are great, and are the work of many dedicated people. I’m one of many. This book is intended to augment those docs, and not replace them. If it appears sometimes that I have copied shamelessly from the documentation, I humbly ask you to remember that I participated in writing those docs, and the edits flowed both directions — that is, sometimes it was the docs that shamelessly copied from the book.

This book does not attempt to be a comprehensive book about the Apache web server.

You should also acquire a copy of Jeffrey Friedl’s excellent book, Mastering Regular Expressions - While the book is several years old, it is still the best book on the topic.

Technical details

This book was written in Markdown, using vim — <> — and built using gitbook —

Previous incarnations were written in LaTeX, ReStructuredText, AsciiDoc, and who knows what else. There always seems to be a new book format out there. It’s exhausting.

You can always obtain the most recent version of the book at, and you’ll usually be able to buy a fairly recent version in the Amazon Kindle store. Some day, there will hopefully be a printed version, too.

Contact information, and errata reporting

If you’d like to get involved in the creation of this book, or if you’d like to tell me about something that needs fixed, Go to GitHub - - and either submit pull requests or open a ticket. If you don’t know what that means, you are welcome to submit errata to <>, and some day there will be a handy way to do this on the website. Not today.

This book is a work in progress. If you purchased the book in electronic form, you should be eligible to receive updates from wherever you bought it. If you’re not, send me your email receipt <>, and I’ll send you an updated version.

About the Author

Rich Bowen has been involved on the Apache http server documentation since about 1998. He is also the author of Apache Cookbook, and The Definitive Guide to Apache mod_rewrite. You can frequently find him in \#httpd, on under the name of DrBacchus or rbowen.

Rich works at Red Hat, in the OSAS (Open Source and Standards) group, where he is an Open Source Community Manager. See for details.

He lives in Lexington, Kentucky, with his wife and kids.


Thanks to fajita, and the other regulars on #httpd (on the network). fajita is my research assistant, and knows more than everyone else on the channel put together. And the folks on #ahd who keep me sane. Or insane. Depending on how you measure. A warm hog to each of you.

None of this would be possible without mod_rewrite itself, so a big thank you to Ralf Engelschall for creating it, and all the many people who have worked on the code and documentation since then.

Finally, a thank you to my muses, Rhi, Z, and E.

And to Maria, who makes everything beautiful. And so that was all right, Best Beloved. Do you see?


mod_rewrite book






No releases published


No packages published