How to Add a Featured Image to a WordPress Post: Complete Guide

Knowing how to add a featured image to a WordPress post is one of the most essential skills for anyone managing a WordPress website. A featured image — sometimes called a post thumbnail — is the representative image that appears at the top of your post, on archive pages, in social media previews, and even in Google search results. Getting it right can significantly improve click-through rates, user engagement, and the overall professional appearance of your site.

What Is a Featured Image in WordPress?

A featured image is a single image that is officially associated with a post, page, or custom post type in WordPress. Unlike images you embed inside the body of your content, the featured image is stored separately in the post metadata and is displayed by your theme in locations it defines — typically at the top of a post or as a thumbnail in post listings.

Featured images are sometimes confused with ordinary inline images, but they serve a distinct purpose. They are referenced by the theme via template tags and can be pulled in by plugins, SEO tools, and social sharing platforms automatically.

Why Featured Images Matter

• SEO benefits: Search engines can index and display your featured image in visual search results.
• Social sharing: Platforms like Facebook, Twitter, and LinkedIn use the featured image as the preview thumbnail when your post is shared.
• User experience: A compelling featured image draws readers in and sets the visual tone for your content.
• Theme consistency: Most WordPress themes are designed with featured images in mind, ensuring a uniform look across your site.

Requirements Before You Add a Featured Image

Before diving into the steps, make sure the following conditions are met so you avoid common pitfalls.

Theme Support

Your active WordPress theme must declare support for featured images (post thumbnails). Most modern themes do this automatically. If you are using a custom or older theme, you may need to add support manually. Open your theme's functions.php file and add the following line:

add_theme_support( 'post-thumbnails' );

Without this line, the Featured Image meta box will not appear in the post editor, and the image will not be displayed by the theme even if you manage to set it programmatically.

Image Size and Format Recommendations

• Format: JPEG for photographs, PNG for graphics with transparency, WebP for modern optimised delivery.
• Dimensions: Check your theme documentation. A common safe size is 1200 × 628 pixels, which also satisfies Open Graph requirements for social sharing.
• File size: Aim for under 200 KB after compression to keep page load times fast.

How to Add a Featured Image Using the Block Editor (Gutenberg)

The WordPress Block Editor, also known as Gutenberg, is the default editor since WordPress 5.0. Adding a featured image here is straightforward.

Step-by-Step Instructions

1. Log in to your WordPress dashboard and navigate to Posts > Add New or open an existing post you want to edit.
2. In the right-hand sidebar, locate the Post tab (not the Block tab). If the sidebar is not visible, click the gear icon in the top-right corner of the editor to open it.
3. Scroll down in the sidebar until you see the Featured image panel. Click on it to expand it.
4. Click the Set featured image link inside the panel. The WordPress Media Library will open.
5. To use an existing image, click on it in the Media Library and then click Set featured image in the bottom-right corner.
6. To upload a new image, click the Upload files tab at the top of the Media Library, drag and drop your image file, or click Select Files to browse your computer.
7. Once uploaded, make sure your new image is selected (it will have a blue checkmark), then click Set featured image.
8. You will see a thumbnail preview of your chosen image in the Featured image panel of the sidebar.
9. Click Update or Publish to save your changes.

Removing or Replacing a Featured Image in the Block Editor

To remove or swap the featured image, return to the Featured image panel in the sidebar. You will see two options below the thumbnail: Replace (to choose a different image) and Remove featured image (to unset it entirely). Click whichever applies and then save the post.

How to Add a Featured Image Using the Classic Editor

If you are using the Classic Editor plugin or an older version of WordPress, the process is slightly different but equally simple.

Step-by-Step Instructions

1. Open the post or page you want to edit inside the Classic Editor.
2. Look at the right-hand sidebar for a meta box labelled Featured Image. If you do not see it, click Screen Options in the top-right corner of the page and make sure Featured Image is checked.
3. Click the Set featured image link inside the meta box.
4. The Media Library dialog will open. Select an existing image or upload a new one from your computer.
5. With your desired image selected, click Set featured image in the bottom-right of the dialog.
6. The meta box will now display a thumbnail of your chosen image.
7. Click Update or Publish to save the post.

How to Add a Featured Image Programmatically

For developers who need to set featured images in bulk, during theme development, or as part of an automated workflow, WordPress provides programmatic methods through PHP functions and WP-CLI.

Using PHP to Set a Featured Image

WordPress provides the set_post_thumbnail() function to assign a featured image to any post. You need the post ID and the attachment ID (the ID of the image in the Media Library).

<?php
// Set a featured image programmatically
$post_id       = 42;   // The ID of the post you want to update
$attachment_id = 187;  // The ID of the image in the Media Library

$result = set_post_thumbnail( $post_id, $attachment_id );

if ( $result ) {
    echo 'Featured image set successfully.';
} else {
    echo 'Failed to set featured image.';
}
?>

You can also remove a featured image programmatically using delete_post_thumbnail( $post_id ), and retrieve the current thumbnail ID using get_post_thumbnail_id( $post_id ).

Using WP-CLI to Set a Featured Image

WP-CLI is the command-line interface for WordPress and is ideal for bulk operations on servers where you have SSH access. To set a featured image from the command line, use the following command:

wp post meta update 42 _thumbnail_id 187 --path=/var/www/html/wordpress

In this command, 42 is the post ID, 187 is the attachment ID of the image, and the --path flag points to your WordPress installation directory. You can also use wp post meta get 42 _thumbnail_id to verify the currently set thumbnail.

Uploading an Image and Setting It as Featured via WP-CLI

1. First, import the image file into the Media Library and note the returned attachment ID:

wp media import /path/to/image.jpg --post_id=42 --featured_image

The --featured_image flag automatically sets the imported image as the featured image for the specified post. This is the most efficient single-command approach when working with WP-CLI.

Troubleshooting Common Featured Image Problems

Even experienced WordPress users run into issues with featured images from time to time. Here are the most common problems and how to fix them.

Featured Image Panel Is Not Showing

If you cannot find the Featured Image panel in the editor, the most likely causes are:

• Your theme does not declare add_theme_support( 'post-thumbnails' ) — add it to functions.php.
• In the Classic Editor, the panel is hidden — enable it via Screen Options.
• A plugin conflict is hiding the meta box — try disabling plugins one by one to identify the culprit.

Featured Image Is Not Displaying on the Frontend

If you have set a featured image but it does not appear on your live site, check the following:

• Confirm your theme template files include the_post_thumbnail() or get_the_post_thumbnail() where you expect the image to appear.
• Clear any caching plugins (such as WP Super Cache or W3 Total Cache) and reload the page.
• Check your image's attachment page to ensure the file was not deleted from the server.

Featured Image Appears Cropped or Distorted

WordPress automatically generates multiple image sizes when you upload a file. If your theme registers a custom image size that does not match your uploaded image's aspect ratio, WordPress will crop it. You can regenerate image sizes after changing theme settings by using the Regenerate Thumbnails plugin or via WP-CLI:

wp media regenerate --yes

Featured Image Not Showing in Social Media Previews

Social platforms rely on Open Graph meta tags to determine which image to display. Most SEO plugins (such as Yoast SEO or Rank Math) automatically use the featured image as the Open Graph image. Make sure your SEO plugin is active and correctly configured, and use a tool like the Facebook Sharing Debugger to scrape fresh metadata.

Frequently Asked Questions

Why is the featured image option not showing in my WordPress editor?

The featured image panel may be missing because your theme does not support post thumbnails. Add add_theme_support( 'post-thumbnails' ); to your theme's functions.php file. In the Classic Editor, you may also need to enable it via the Screen Options dropdown at the top of the editing screen.

What is the ideal featured image size for WordPress?

The ideal size depends on your theme, but a widely recommended dimension is 1200 × 628 pixels. This covers most theme layouts and also satisfies the Open Graph image requirements used by Facebook and LinkedIn for social sharing previews. Always check your specific theme's documentation for its recommended dimensions.

Can I set a featured image for multiple posts at once?

Yes, using WP-CLI you can script bulk updates with the wp post meta update command inside a loop. Alternatively, plugins like Quick Featured Images allow you to assign featured images to multiple posts from the WordPress dashboard without writing any code.

Does a featured image affect SEO?

Featured images can positively impact SEO in several ways. They appear in Google Image Search, are used as Open Graph images for rich social previews which can increase click-through rates, and contribute to the overall visual quality and user engagement metrics of your page — all of which are indirect SEO signals.

Adding a featured image to your WordPress posts is a small step that makes a big difference in how your content is perceived across your website, search engines, and social media platforms. Whether you prefer clicking through the block editor, writing PHP functions, or running WP-CLI commands on your server, WordPress gives you flexible options to suit every workflow. If you want an even faster way to manage tasks like this without digging through menus or code, WP AI Agent is a powerful tool that lets you handle WordPress tasks — including setting featured images, updating post metadata, and much more — simply by typing natural-language instructions in an AI chat interface.