Skip to Main Content

Disable Attachment Pages the WordPress Way

One of the oddest remnants of the early versions of WordPress are attachment pages. I can count on one finger the number of times I’ve thought “I’d like a dedicated page for every image on my site”. Normally, unused and illogical features like this can just be ignored. However, attachment pages aren’t just a harmless remnant of a bygone era.

Attachment pages have dedicated urls, that are based on the name of the image, and overlap with the slugs you can set for posts, pages, and custom post types. Because of this, if you upload an image named faq.jpg, you may find yourself unable to add a page at the address /faq. This can negatively impact your SEO, and is an incredibly frustrating issue to try to identify and explain to clients. Beyond the URL issue, they are another template that needs to be fully themed and branded, just in case a client runs across the page by accident. As such, they need to die.


All other post types are easy to deal with, with filters and functions to control their use of URLs. Attachments stand alone with an overly-complicated and immutable permalink structure, and no simple filters attached.

There are many snippets and instructions online detailing how to remove these pages, but most (if not all) of them simply patch over the issue with a 301 redirect or a forced 404 page. Unfortunately, those authors don’t solve the root issue of reserved slugs.

So, in that light, I wrote the definitive solution to fully disable attachment pages.

Running the plugin provided below will:

  • remove all rewrite rules for attachments
  • prevent attachments from reserving url paths
  • prefix all slugs for new attachments, in case the plugin is ever deactivated, to minimize potential name conflicts
  • rewrite all references to attachment pages urls to point to the url of the file itself
  • as a final fallback, in case some sort of custom code requests an attachment page via code, that page will redirect to the attachment file.

The only further change that could be made, would be to remove the references to attachment pages that appear in the media library. Unfortunately, to do so, I would have to either completely replace the backbone templates in use, as they offer no filters for this text, or I would have to blindly parse the HTML with regular expressions, which is impossible to do without introducing undocumented bugs. Neither of these solutions is particularly acceptable or future-proof. However, both places that attachment pages are referenced make reasonable sense as links to the attachment file, so the impact to the user experience is trivial. Hopefully the JavaScript over haul that is currently beginning with the Gutenberg editor will eventually lead to a more flexible media library that allows for this sort of customization.

To install the plugin, simply copy the following code to a new folder in your plugins.php directory. If there is enough interest in the comments, I will deploy the code as a plugin on the plugin repository, to make it simpler to install.




  1. Matt's profile image.

    Great plugin, much appreciated. I’d suggest that you put this on github as a wordpress-plugin project with a composer.json so I can just include it in my own composer.json and reference your github link to get updates.

    • gschoppe's profile image.

      If I release on the WordPress plugin repository, wp-packagist will take care of that, right? If so, that seems like a more universal option for users

    • gschoppe's profile image.

      Can you point to a specific trope or area that has you confused? My style appears to match the WordPress PHP Coding Standards.

      I’ll take a look at that linter later, as it may be useful, but most of WordPress’s standards match with PSR-4 (other than tabbing), which my style is based on.

      If you are having trouble with reading the wp_unique_post_slug function, there isn’t much I can do about that. To make it easier to patch/upgrade the plugin to match future changes to core, the logic of that function is a 1-to-1 copy of the inner portion of WordPress core’s wp_unique_post_slug function, which is unfortunately incredibly confusing to read. I could refactor, but it would make it significantly harder to patch the plugin if core changes anything in that logic, as I wouldn’t be able to generate and apply a patch file from the core code.

    • gschoppe's profile image.

      if I release on the WordPress Repository, I’ll make sure to prefix the slug, and I definitely recommend prefixing the file name when adding to a WordPress project now (in the gist itself. the file is named gjs-disable-attachment-pages.php, to prevent conflicts), however I don’t want to stray too far from the actual task that it accomplishes, otherwise people will continue to install the version with the simpler name to google… Perhaps I’ll add in the word “Better”, or something… I’ve seen that before.

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>