WordPress Theme Screenshot: Size, Format, Filename and How to Make One

A WordPress theme screenshot is a 1200×900 pixel image (4:3 ratio) named screenshot.png, saved in the root of the theme folder next to style.css. WordPress shows it under Appearance -> Themes, and the WordPress.org theme directory uses it as the theme’s thumbnail. PNG and JPG are the documented formats, and 1200×900 is also the largest size the directory accepts.

Building a child theme? Our child theme generator creates the theme files for you. The screenshot is the one piece you add yourself, and this page covers how.

Below you’ll find the full requirements table, the exact order WordPress checks file extensions in (WebP and AVIF work, with a catch), why a replaced screenshot sometimes refuses to update, and three ways to generate one at exactly the right size. If you came here for the small icon in the browser tab, that is your site icon, not the theme screenshot: see how to add a favicon in WordPress (Settings > General > Site Icon).

WordPress Theme Screenshot Requirements

WordPress core is lenient about the screenshot. The WordPress.org theme directory is not. If you only use the theme on your own site, the middle column is what matters. If you plan to submit it, follow the right-hand column.

Requirement	What WordPress core accepts	What the WordPress.org directory requires
Filename	screenshot plus a lowercase extension	screenshot.png or screenshot.jpg
Location	Root of the theme folder (same folder as style.css)	Same
Formats	PNG, GIF, JPG, JPEG, WebP (5.8+), AVIF (6.5+)	PNG or JPG
Dimensions	Any size, served as-is	No bigger than 1200×900, and 1200×900 is the recommended size
Aspect ratio	Any, but the admin tile assumes 4:3 or 3:2	Exactly 4:3
Number of files	One (the first match wins)	One
Content	Anything	Must show what the theme looks like and must not look like an advertisement
Child themes	Never inherit the parent’s screenshot	Need their own screenshot

The directory rules come from the Theme Review requirements, which say the screenshot “must not be bigger than 1200 x 900px,” the ratio “needs to be 4:3,” and it “must not look like an advertisement.” Reviewers can also ask you to change a screenshot they find inappropriate.

Recommended WordPress Theme Screenshot Size

The recommended size for a WordPress theme screenshot is 1200 pixels wide by 900 pixels tall, a 4:3 aspect ratio. The Theme Handbook describes screenshot.png as “a 1200×900 screenshot image of your theme,” and it’s a fixed number, unlike featured image size, which depends on your theme. Twenty Twenty-Five, the newest default theme bundled with WordPress 7.1, ships a 1200×900 PNG.

You don’t need a 2x version. The Theme Check plugin (the automated test every directory submission runs through) says 1200×900 is the size “to account for HiDPI displays.” The largest tile WordPress ever draws in the admin is 440px wide, so 1200px is already more than double that.

Going bigger causes a hard failure if you submit to WordPress.org. Theme Check flags anything over 1200×900 as REQUIRED, with a message like “Screenshot is wrong size! Detected: 2400×1800. Maximum allowed size is 1200x900px.” A smaller 4:3 image such as 800×600 passes with only a recommendation to use 1200×900.

Keep the important part out of the bottom 100 pixels

On the Appearance -> Themes screen, each tile is a 3:2 box on admin screens narrower than 1640px, according to core’s themes.css. Your 4:3 image is pinned to the top and stretched to the tile’s width, so the overflow at the bottom is hidden. On a 1200×900 screenshot, that’s the bottom 100 pixels (about 11%).

On very wide screens (1640px and up) the tile switches to 4:3 and shows the whole image. Design for the smaller case: keep logos, headings and anything that identifies the theme in the top 800 pixels.

WordPress Theme Screenshot File format

Use PNG or JPG. The Theme Handbook says “both .png and .jpg are acceptable file formats,” and they’re the only two Theme Check looks for. PNG suits flat, UI-heavy designs. JPG is usually smaller for photo-heavy themes.

Core itself accepts more. Here’s the exact loop from WP_Theme::get_screenshot() (see the code reference):

foreach ( array( 'png', 'gif', 'jpg', 'jpeg', 'webp', 'avif' ) as $ext ) {
	if ( file_exists( $this->get_stylesheet_directory() . "/screenshot.$ext" ) ) {
		$this->cache_add( 'screenshot', 'screenshot.' . $ext );
		// ...returns the relative path or the full URL
	}
}

Two things follow from that loop:

• The order is a priority list. If a theme has both screenshot.png and screenshot.webp, WordPress shows the PNG and ignores the WebP.
• WebP was added in WordPress 5.8 and AVIF in 6.5. On older versions those files are simply not found, and the tile shows up blank.

Extension	Checked since	Passes Theme Check?
.png	WordPress 3.4 (when WP_Theme was introduced)	Yes
.gif	WordPress 3.4	No
.jpg / .jpeg	WordPress 3.4	.jpg only
.webp	WordPress 5.8	No
.avif	WordPress 6.5	No

So WebP is fine for a private theme on a current site. For a theme you’ll submit to WordPress.org, a WebP-only theme fails Theme Check with “No screenshot detected! Please include a screenshot.png or screenshot.jpg.”

WordPress Theme Screenshot Filename

The file must be named screenshot with a lowercase extension: screenshot.png or screenshot.jpg. Core builds the path as /screenshot.$ext using lowercase extensions, and most Linux web servers treat filenames as case-sensitive, so Screenshot.PNG or screenshot-1200x900.png won’t be found.

How to Add a Screenshot to a WordPress Theme

The screenshot lives at the root of the theme folder, alongside the style.css file that defines the theme. This is the same for classic themes and block themes. The full path looks like this:

wp-content/
  themes/
    your-theme/
      style.css
      screenshot.png   <-- here
      functions.php
      index.php

To replace or add a screenshot for a theme already installed on a site:

1. Create the image at 1200×900 and save it as screenshot.png (or screenshot.jpg).
2. Connect to your site via SFTP, SSH, or your WordPress host’s file manager.
3. Navigate to /wp-content/themes/your-theme-folder/.
4. Upload the new file, overwriting the existing one. Delete any other screenshot.* files so an older PNG doesn’t win the priority order.
5. Bump the Version: line in the theme’s style.css (for example 1.0.0 to 1.0.1), then reload Appearance -> Themes.

The next section explains why step 5 matters.

Why your new screenshot still shows the old image

The Themes screen doesn’t request screenshot.png on its own. It requests screenshot.png?ver=1.0.0, with the theme’s version number from style.css appended. That’s in core’s wp-admin/themes.php and the JavaScript theme templates.

If you swap the file but leave the version alone, the URL is identical, so your browser, a CDN or a caching plugin can keep serving the old image. Changing the version changes the URL and forces a fresh download. It’s the same cache-busting job the ver query string does for your CSS and JavaScript.

On the server side, core caches which screenshot file it found in the themes object cache group. By default that group isn’t persistent, so it resets on every page load. Only if something enables the wp_cache_themes_persistently filter does it stick around (for 30 minutes by default, or until the theme cache is cleared).

Child themes need their own screenshot

A child theme in WordPress inherits templates and styles from its parent, but not the screenshot. The docblock on get_screenshot() says it plainly: “parent theme screenshots are not inherited.” Without its own file, a child theme shows a blank tile.

You can copy the parent’s screenshot.png into the child theme folder as a starting point. A better option is a version with a small label such as “Child” so you can tell the two apart in the dashboard.

How to Make a Theme Screenshot (Screenshot Generator Options)

There’s no screenshot generator built into WordPress, and our child theme generator doesn’t create one either. You don’t need a dedicated tool, though. Any browser or a one-line command gets you an exact 1200×900 capture of the theme’s front page.

Option 1: Browser DevTools (no install)

1. Open the site in Chrome, Edge or Brave and open DevTools.
2. Click Toggle device toolbar and set the dimensions to Responsive.
3. Type 1200 and 900 into the width and height fields.
4. Open More options (the three dots), choose Add device pixel ratio, and set DPR to 1. On a high-DPI display the capture can otherwise come out at 2x (2400×1800).
5. From the same menu, choose Capture screenshot. Rename the download to screenshot.png.

The menu labels come from Google’s device mode documentation.

Option 2: Headless Chrome from the command line

Any Chromium-based browser can save a screenshot without opening a window. This produces a 1200×900 PNG:

google-chrome --headless --hide-scrollbars --window-size=1200,900 \
  --screenshot=screenshot.png https://your-site.test/

On a Mac, replace google-chrome with the full path, such as "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome". Run it against a local or staging copy of the site loaded with demo content.

Option 3: Playwright (scriptable, good for many themes)

If you build several themes, Playwright’s CLI is easy to drop into a build script. After a one-time npx playwright install chromium:

npx playwright screenshot --viewport-size "1200, 900" https://your-site.test/ screenshot.png

Add --wait-for-timeout 2000 if the page has animations or lazy-loaded images that need a moment to settle.

Tips for a screenshot that passes review

• Capture the theme as it actually looks. A designed mockup is fine, but the directory rules require that it represent the theme and not read like an ad.
• Use demo content and images you have the rights to use. The review requirements also ban images that promote hate or violence and images showing recognizable children.
• Run the image through a lossless optimizer before shipping. It’s downloaded every time someone loads the Themes screen.
• Check it in the Theme Check plugin before submitting. It catches the wrong size, the wrong ratio and missing files.

Why Are WordPress Theme Screenshots Important?

The screenshot is the first image visitors see when browsing the WordPress.org theme directory, and it’s how site owners tell themes apart inside their dashboard. For a theme you intend to publish, it’s effectively the cover image that decides whether anyone clicks through to the description.

For a private or child theme on your own site, it matters less. It still makes Appearance -> Themes easier to scan when you have several themes installed, and it’s worth pruning that list too: our guide on deleting WordPress themes covers which ones are safe to remove.

---

Frequently Asked Questions

---

Wrapping Up

The short version: 1200×900 PNG or JPG, named screenshot.png (or .jpg), in the root of the theme folder. Don’t go bigger, keep the key details out of the bottom 100 pixels, and bump the theme version when you replace it so the admin shows the new one.