Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Setup & site building · Guide

How to Flush Permalinks in WordPress (Step by Step)

How to Flush Permalinks in WordPress (Step by Step)

Short answer

Go to Settings, then Permalinks, and click Save Changes without changing anything. WordPress rebuilds its rewrite rules and updates the htaccess file on Apache if it can. You can also run wp rewrite flush in WP-CLI, and developers can call flush_rewrite_rules on plugin activation.

Key takeaways

  • Saving the Permalinks screen flushes the rewrite rules.
  • Flushing fixes 404 errors after new post types or migrations.
  • WP-CLI offers wp rewrite flush, with a hard flag for htaccess.
  • Developers should flush only on activation, never on every load.
  • Nginx sites need a try_files rule, since they have no htaccess.
  • Clear all caches after flushing to remove cached 404 pages.

Go to Settings, then Permalinks, and click Save Changes without changing anything; WordPress rebuilds its rewrite rules and, on Apache servers, rewrites the htaccess file if it can.

Flushing permalinks means telling WordPress to regenerate the rules that map pretty URLs to the right content. It is one of the most common fixes for pages that suddenly return 404 errors.

You do not lose any content or settings by doing it. The permalink structure stays the same unless you choose a different one.

This guide covers the dashboard method, WP-CLI, code for developers, and what to do when flushing does not help.

It deletes WordPress's stored rewrite rules and builds a fresh set from the current permalink structure, post types and taxonomies, then saves them in the database.

WordPress keeps its rewrite rules in an option called rewrite_rules. When a request comes in, WordPress matches the URL against these rules to decide which post, page or archive to load.

If a plugin adds a new post type or a new URL pattern, the stored rules do not know about it until they are rebuilt. URLs that should work then return a 404 error.

The Rewrite API documentation explains how these rules are built. Our explainer on what a permalink is covers the basics.

Flush them after adding a custom post type or taxonomy, after a migration, after changing the permalink structure, or when posts and pages suddenly return 404 errors.

Common situations include:

  • A new plugin's pages, such as a portfolio or event listing, show Page not found.
  • You moved the site to a new host or domain.
  • You changed a custom post type's slug in code.
  • WooCommerce product or category pages return 404 errors after setup.
  • Pages broke after restoring a backup.

If URLs work but show the wrong content, the cause is usually a slug conflict rather than stale rules. Flushing will not fix that.

Flushing is also a sensible first step after updating a plugin that adds its own URLs, such as a membership, forum or directory plugin. Updates sometimes change rewrite rules, and a quick save of the Permalinks screen brings the stored rules up to date.

Log in, go to Settings, then Permalinks, leave the current structure selected, scroll down and click Save Changes.

That single click is enough. WordPress regenerates the rules as soon as the screen saves.

Even just visiting the Permalinks screen triggers a soft flush in many cases, but clicking Save Changes is the reliable way.

The Settings Permalinks Screen documentation describes the structures available on this page. Our guide to setting up permalinks helps you choose one if you have not yet.

After saving, open a page that was returning a 404 error in a private window. If you use a caching plugin, clear the cache first.

If the Save Changes button seems to do nothing, check that you are logged in as an administrator. Other roles cannot manage settings, and the Permalinks screen will not appear in their menu at all.

On a multisite network, each site has its own rewrite rules. Flush on the specific site with the broken URLs, not only on the main site.

Run the command wp rewrite flush in your site's directory, and add the hard flag if you also want WordPress to rewrite the htaccess file.

WP-CLI is handy when you cannot reach the dashboard or manage many sites. The commands are:

wp rewrite flush
wp rewrite flush --hard

The first rebuilds the rules in the database. The second also attempts to update the server rewrite file on Apache. The wp rewrite flush reference lists the options.

You can also check the current structure with wp rewrite structure or list rules with wp rewrite list. Our list of useful WP-CLI commands includes more tools for site maintenance.

How do developers flush rewrite rules in code?

Call flush_rewrite_rules() once, usually on plugin activation and deactivation, after registering your post types; never call it on every page load.

Flushing is slow, because WordPress has to rebuild every rule and save a large option to the database. Running it on each request can slow a site badly.

A typical pattern in a plugin looks like this:

function myplugin_activate() {
    myplugin_register_post_types();
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_deactivate() {
    flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'myplugin_deactivate' );

The flush_rewrite_rules() reference explains the hard and soft modes. Register the post type before flushing, or the new rules will be missing.

Our guide on creating a custom post type shows where this fits.

What is the difference between a soft and hard flush?

A soft flush only rebuilds the rules stored in the database, while a hard flush also tries to write the htaccess file on Apache servers.

TypeDatabase ruleshtaccess fileHow to trigger
Soft flushRebuiltNot touchedflush_rewrite_rules( false )
Hard flushRebuiltRewritten if writableSave Permalinks, default function, or the hard CLI flag

Most of the time the difference does not matter. It becomes important when the htaccess file is missing or damaged.

What if flushing does not fix the 404 errors?

Check that the server's rewrite rules are in place: the htaccess file on Apache or LiteSpeed, or the try_files rule in the Nginx configuration.

WordPress can rebuild its own rules, but the web server must also send pretty URLs to WordPress.

On Apache or LiteSpeed, the htaccess file in your site's root should contain the standard WordPress block. If the file is not writable, WordPress shows the rules on the Permalinks screen for you to copy in by hand.

Our guide on editing the htaccess file shows how. Apache also needs the mod_rewrite module enabled.

On Nginx, there is no htaccess file. The server configuration needs a rule that passes unknown URLs to WordPress, usually with the try_files directive. Your host normally handles this.

If permalinks are still broken after these checks, see our full guide to fixing permalinks not working.

Can caching hide the result of a flush?

Yes; a page cache, server cache or CDN may keep serving the old 404 response, so clear every cache layer after flushing.

Many caching tools store 404 pages as well as normal pages. After you fix the rules, the cached error can stay for minutes or hours.

Clear the caching plugin, any host-level cache, and your CDN, then test again in a private window. Our guide on clearing cache in WordPress covers each layer.

Yes; it does not change URLs, content or settings, and it is safe to repeat, though a hard flush can overwrite custom rules inside the WordPress section of htaccess.

WordPress only manages the part of the htaccess file between its BEGIN WordPress and END WordPress markers. Put your own rules outside those markers so they survive a flush.

Take a quick copy of the htaccess file before flushing on a site with custom redirects or security rules. It takes seconds and avoids surprises.

On managed hosts that do not let WordPress write to the htaccess file, a hard flush simply skips that step. The database rules are still rebuilt, so the flush is still worth doing.

Only when something changes, such as a new post type, a migration or sudden 404 errors; there is no need to flush on a schedule.

WordPress and well-built plugins flush automatically at the right times. Regular manual flushing adds nothing.

If you find yourself flushing often to keep pages working, something is resetting the rules. Look for a plugin that calls the flush function on every load, or a deployment process that replaces the htaccess file.

A simple way to find the culprit is to check the Permalinks screen after each plugin update for a few days. When pages break again, the most recently changed plugin is the first suspect. Our guide to fixing a plugin conflict explains how to confirm it.

Frequently asked questions

Will flushing permalinks change my URLs?

No. Flushing rebuilds the rules for your current permalink structure. URLs stay the same unless you select a different structure on the Permalinks screen before saving. Content, settings and redirects stored in plugins are not affected.

Do I need to change anything before clicking Save Changes?

No. Leave every setting as it is and click Save Changes. The save itself triggers the flush. Changing the structure is only needed if you actually want different URLs, which can affect SEO and require redirects.

Why do my custom post type pages show 404 errors?

The rewrite rules were probably built before the post type was registered, so WordPress does not recognize its URLs. Flush permalinks by saving the Permalinks screen. If you wrote the post type code yourself, flush once on plugin activation after registering it.

Can I flush permalinks without logging in to WordPress?

Yes, with WP-CLI. Connect to the server over SSH and run wp rewrite flush from the WordPress folder. Many hosts also offer WP-CLI in their control panel or a terminal tool. Without either, you need dashboard access.

Does flushing permalinks affect site speed?

A single flush takes a moment and has no lasting effect. Flushing on every page load, which some poorly written code does, is expensive because it rebuilds and saves every rule each time. That can slow the site noticeably.

Sources

  1. Settings Permalinks Screen WordPress.org Documentation
  2. flush_rewrite_rules() WordPress Developer Resources
  3. wp rewrite flush WordPress Developer Resources
  4. Rewrite API WordPress Developer Resources
  5. Apache Module mod_rewrite Apache HTTP Server
  6. Module ngx_http_core_module nginx

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.