Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
In a classic PHP theme, create attachment.php for a custom layout shared by all attachment pages. To specialize image attachments, use image.php; for a narrower match such as JPEG files, use jpeg.php or image-jpeg.php. Block themes use the equivalent .html templates. WordPress selects the most specific matching template first, but attachment pages must be enabled and the visitor must open the attachment page—not just the media file URL.
Choose the right attachment template
The right filename depends on how broadly the layout should apply and whether the theme uses PHP templates or block templates. For a classic theme, WordPress checks these files in order:
{mime_type}-{sub_type}.php{sub_type}.php{mime_type}.phpattachment.phpsingle-attachment.phpsingle.phpsingular.phpindex.php
For an image/jpeg attachment, the specific candidates are image-jpeg.php, jpeg.php, and image.php, followed by attachment.php and the general fallbacks. WordPress resolves this hierarchy through get_attachment_template(); developers can also alter the candidate hierarchy using its attachment-template filters.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches| Template | Scope | When to use it |
|---|---|---|
attachment.php |
All attachment types | Use for a common attachment-page design. |
image.php, video.php, audio.php, or application.php |
A MIME type | Use when that media category needs a distinct layout. |
jpeg.php or image-jpeg.php |
A subtype, or a MIME-type/subtype combination | Use when a narrower match needs its own design. |
Use a child theme or your own custom theme rather than editing a vendor theme: a parent theme update can overwrite direct changes.
#1 Best Overall
Create a template in a classic PHP theme
- Open the active child or custom theme directory. Place the template file at the theme root, alongside files such as
single.phpandindex.php. - Choose the filename. Add
attachment.phpfor a shared layout, or choose a more specific filename such asimage.phporimage-jpeg.php. - Use the theme’s standard page structure. Include its header, loop, and footer so the page retains the site’s normal layout and behavior.
- Render the attachment inside the loop. For an image attachment, the WordPress Theme Handbook documents this pattern for displaying the image and an optional excerpt caption:
<div class="entry-attachment"> <?php $image_size = apply_filters( 'wporg_attachment_size', 'large' ); echo wp_get_attachment_image( get_the_ID(), $image_size ); ?> <?php if ( has_excerpt() ) : ?> <div class="entry-caption"> <?php the_excerpt(); ?> </div> <?php endif; ?> </div>WordPress’s attachment-template documentation shows the example, and the function reference for
wp_get_attachment_image()explains the image-rendering function. - Adapt the markup and styling. Add the metadata, CSS, and accessibility details your site needs; the example’s size filter is a hook, not a requirement to keep that exact value.
Use an attachment template in a block theme
Block themes use HTML templates in the theme’s templates directory rather than PHP files at the theme root. The matching order follows the same specificity pattern:
{mime_type}-{sub_type}.html{sub_type}.html{mime_type}.htmlattachment.html- The default single-template hierarchy
For an image/jpeg attachment, use image-jpeg.html, jpeg.html, or image.html for progressively broader matches, or attachment.html for all attachments. The WordPress template hierarchy documentation describes the block-theme attachment order.
Quick Recap
Best Value
Rank #4
Rank #3
Troubleshoot a template that does not load
- Confirm that the URL is an attachment page. A media item can link directly to its raw file rather than to its attachment page. A template controls the page view, not the raw file served by the media URL.
- Check whether attachment pages are enabled. WordPress states: “As of WordPress 6.4, attachment pages are no longer enabled by default on new installations.” This default applies to new installations; if the page is unavailable, verify the site’s attachment-page behavior before changing template files. See the Theme Handbook’s template hierarchy guidance.
- Check the candidate order and filename. A more specific existing file, such as
image-jpeg.php, takes precedence overimage.phpandattachment.php. Verify the file is in the correct theme location and matches the attachment’s MIME type and subtype. - Check the theme technology. A block theme looks for HTML templates in
templates; adding a PHP attachment template will not serve as its block-template equivalent.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
