What file WordPress actually looks for
WordPress looks for a file literally named screenshot in the theme's root folder, checking for extensions in this order: png, jpg, jpeg, gif. It does not matter what the image is called anywhere else in your project; if the theme folder does not contain screenshot.png (or one of the accepted alternatives) at the top level, Appearance → Themes shows a plain gray placeholder box instead of a preview.
Getting the dimensions and aspect ratio right
WordPress recommends a screenshot at 1200x900 pixels, a 4:3 aspect ratio. Older documentation references 880x660, and WordPress will still display images at other sizes, but they get scaled and can look stretched, blurry, or cropped oddly inside the theme card in the grid view.
For a theme captured from a live website, taking a full-page or above-the-fold screenshot at a high resolution and then cropping it to 1200x900 before saving as PNG gives the sharpest, least distorted result in the admin grid.
Case sensitivity and naming mistakes
On Linux-based hosting, which is the vast majority of WordPress hosts, file names are case-sensitive. Screenshot.png, ScreenShot.PNG, or screenshot.JPG (uppercase extension) will not be picked up because WordPress checks for the lowercase pattern. Rename the file to exactly screenshot.png (or screenshot.jpg) in all lowercase to fix this.
- Open the theme folder in wp-content/themes/your-theme/.
- Confirm the screenshot file is named exactly screenshot.png, screenshot.jpg, screenshot.jpeg, or screenshot.gif, all lowercase.
- Confirm it sits directly in the theme root, not inside an assets or images subfolder.
- Resize or crop it to 1200x900px if it is a very different aspect ratio.
- Re-upload the file via FTP/SFTP or replace it in your local files and re-zip if reinstalling.
Clearing WordPress and browser caches
Even after fixing the file, the Themes screen can keep showing the old placeholder or an old image because WordPress caches theme data and the browser caches the image itself. Hard-refresh the Appearance → Themes page (Ctrl+Shift+R or Cmd+Shift+R), and if you use a caching plugin or object cache, clear it since some plugins cache admin screens more aggressively than expected.
If you are testing locally, also check that your local server is not serving a stale file from an OPcache or filesystem cache layer, common with some Docker-based local environments.
When the image shows in some browsers but not others
This is typically a browser-level image cache issue rather than anything WordPress-specific, since the previous screenshot.png was already fetched and cached under that exact URL. Renaming the theme's version number in style.css does not bust this particular cache because the screenshot URL itself has no version query string appended by WordPress core.
Avoiding this problem when converting a live site
When you convert a webpage into a theme, it is easy to forget the screenshot step entirely since it has no functional effect on the site itself. Tools like Themify generate a screenshot automatically as part of the packaged theme output, sized correctly, which removes this as a manual step you can forget under deadline pressure.
Frequently asked questions
- What is the correct WordPress theme screenshot size?
- WordPress recommends 1200x900 pixels, a 4:3 aspect ratio, saved as screenshot.png in the theme's root folder.
- Why does my theme show a gray box instead of a screenshot?
- This means WordPress cannot find a correctly named screenshot file (screenshot.png/jpg/jpeg/gif) in the theme's root directory; check spelling, case, and location.
- Does the screenshot file affect how the theme functions on the site?
- No, screenshot.png is purely cosmetic for the wp-admin theme selection screen and has zero effect on how the live site renders for visitors.
- Can I use a JPG instead of PNG for the screenshot?
- Yes, WordPress accepts screenshot.jpg, screenshot.jpeg, screenshot.png, and screenshot.gif, checked in that priority order in the theme folder.