Gold Penguin Logo with Text

How the add_rewrite_rule() works in WordPress 2023

The add_rewrite_rule function in WordPress allows you to create and modify URL structures in WordPress. We'll go over an example and how it works in depth.
Updated January 24, 2023
pasel computer code as digital art
pasel computer code as digital art

Sometimes you'll need to specify additional rewrite rules for WordPress. For example, you might want to create a custom URL structure for your blog posts. The add_rewrite_rule() function is the most commonly used function for this purpose. It allows you to specify a new rule that WordPress will use to generate a different URL structure. In some cases, you'll need to use add_rewrite_rule() in conjunction with add_rewrite_tag(). This function allows WordPress to recognize custom post/get variables. Regardless, the function has some extensive capabilities and can be used to create custom URL structures for your WordPress site.

What is the add_rewrite_rule() function do?

The WordPress add_rewrite_rule function is used to create your own custom rewrite rules for WordPress. This can be used for creating pretty permalinks for your pages and posts, or for creating custom Rewrite Rules for other purposes.

The add_rewrite_rule() accepts 3 parameters:

$regex: The first parameter is the regex to match against. This can be anything you want, but it must be a valid regex expression.

$query: The second parameter is not a path, rather it is the query string that will be passed to index.php.

$after: The third parameter is the priority. This is an optional condition that can be used to specify the order in which WordPress should apply your rewrite rules. It accepts 2 possible values: top, or bottom. The default value is bottom.

Examples of the add_rewrite_rule()

Ok so now you know what the function does, but what does it look like in practice? Let's take a look at an example of the add_rewrite_rule() in action. To add a rewrite rule to your WordPress site, you have to add the function somewhere in your functions.php. If you can't add it directly to your functions file, use a Code Snippets plugin to insert it.

In this example, we will create a custom URL structure for a rather complex path to make it easier to visualize. The following code will change the path of your site from to

function gp_rewrite() {

  add_rewrite_rule('^page/([^/]+)/?','index.php?pagename=page&customvariable=$matches[1]', 'top');

add_action( 'init', 'gp_rewrite' );

When using the rewrite rule function, we also had to use the add_rewrite_tag() function. This is because we are using a custom variable in our URL path (custom variable). The add_rewrite_tag() function allows WordPress to recognize custom variables in the URL path.

WordPress add_rewrite_rule() not working?

Carefully tried to make a rewrite and found out something isn't working? Here are a few quick tips:

Did you remember to flush the rewrite rules? After adding a new rule, you will need to visit the Permalinks page in your WordPress admin area to flush the rewrite rules cache.

Check your .htaccess file. If you are manually adding rewrite rules to your .htaccess file, make sure that the new rules are being added to the correct place in the file.

Make sure your regex is correct. One common mistake is to forget to escape special characters in your regex. For example, if you are using the . (dot) character in your regex, you will need to escape it with a backslash. Otherwise, it will be interpreted as a wildcard character.


This function is pretty powerful and can be used to create some pretty creative rewrite rules for your WordPress site. Just remember to keep your regular expressions correct, and to update your .htaccess file when you make changes. Otherwise, your new rewrite rules might not work as expected. Hopefully now you understand a little bit more about how the WordPress add_rewrite_rule function works and how you can use it to create custom URL structures for your WordPress site.

Do you have any questions about how to use the add_rewrite_rule() function in WordPress? Let us know in the comments below!

Want To Learn Even More?
If you enjoyed this article, subscribe to our free monthly newsletter
where we share tips & tricks on how to use tech & AI to grow and optimize your business, career, and life.
Written by Justin Gluska
Justin is the founder of Gold Penguin, a business technology blog that helps people start, grow, and scale their business using AI. The world is changing and he believes it's best to make use of the new technology that is starting to change the world. If it can help you make more money or save you time, he'll write about it!
Notify of

Most Voted
Newest Oldest
Inline Feedbacks
View all comments
Join Our Newsletter!
If you enjoyed this article, subscribe to our newsletter where we share tips & tricks on how to make use of some incredible AI tools that you can use to grow and optimize a business