How to add images to WordPress

Adding an image to WordPress is one of the things people do most often and one of the things people get stuck on most often. The block editor has multiple image-related blocks that look similar but behave differently, the Media Library has its own upload flow, and “HTTP error” during upload is one of the most common WordPress complaints on support forums – usually for a reason that has nothing to do with the image. The good news is that the workflow is consistent once you know which block to pick and what the upload errors actually mean.

This guide walks through the four ways to get an image into a post or page (Image block, Gallery block, drag-and-drop, Media Library), explains the image sizes WordPress generates automatically and why they matter for performance, covers featured images versus inline images, and goes through the upload errors that stop people – including the HTTP error that has nothing to do with HTTP.

The short answer#

In the block editor, click the + button where you want the image, search for Image, and either drag a file from your desktop, click Upload to pick from your computer, or click Media Library to use one already uploaded. The image appears immediately, and its alt text, alignment, link, and caption controls are in the right sidebar.

For a set of images shown together as a grid, use the Gallery block instead – same upload flow, but you select multiple files at once and WordPress arranges them in columns automatically.

For a featured image (the thumbnail that appears in archives, social shares, and at the top of single posts on most themes), look in the right-side Document panel for Featured image and click Set featured image.

The Image block#

The Image block is the right choice for almost every single-image situation – inline images in a paragraph, hero images at the top of a post, screenshots in a tutorial, photos in a gallery row.

Adding an image with the Image block

1. In the editor, click the + button (Add block) where you want the image – either in the toolbar or by pressing Enter on a new line and clicking the + that appears.
2. Search for Image and click it. An empty image placeholder appears.
3. The placeholder has three options: Upload (file picker for files on your computer), Media Library (pick something you have already uploaded), or Insert from URL (link to an image hosted elsewhere – rarely the right answer for a site you control).
4. Pick the option you need. The image appears in the editor.
5. In the right sidebar, fill in the Alt text – this is required for accessibility and SEO, and how to add alt text to images in WordPress covers what to write and what to skip.
6. Optionally set a caption (visible below the image), a link target (clicking the image goes somewhere – the media file, an attachment page, or a custom URL), and alignment (left, center, right, wide, or full width if the theme supports it).

The image is now in your post and uploaded to the Media Library at the same time.

Drag-and-drop from the desktop

Faster than the menu: drag the image file from your desktop or a folder window directly onto the editor. WordPress detects the drop, uploads the file, and inserts an Image block at the cursor position. This works in any block editor area – posts, pages, the Site Editor, even some plugins’ editor screens.

Replace an image with a different one

Click the image to select the block, then click the image icon in the block toolbar (it looks like a small picture frame). The same Upload / Media Library / URL options appear, and picking a new image replaces the current one without losing the alt text, caption, or alignment settings.

The Gallery block#

The Gallery block is the right choice for displaying multiple related images together – a portfolio row, an event recap, a product variant grid. Each image inside the gallery is technically still its own image, but the gallery handles the layout (columns, gaps, click-to-enlarge) without needing CSS.

Adding a gallery

1. Click + to add a block.
2. Search for Gallery.
3. Click Upload to pick multiple files at once (Ctrl-click or Cmd-click for multi-select), or Media Library to pick from existing uploads.
4. The gallery appears with images arranged in columns. The right sidebar lets you set the number of columns, whether images are cropped to a uniform aspect ratio, and what each image links to (none, the media file, or its attachment page).
5. Click any individual image inside the gallery to set its alt text and caption. Each image keeps its own metadata.

The Gallery block is a wrapper around individual Image blocks, so anything you can do to a single image (set alt text, set a custom URL link, change alignment) also works on each image inside the gallery.

Gallery vs columns of Image blocks

Two things you can do that look the same on the front end:

• Gallery block. Built-in column count, click-to-enlarge, and gallery-aware lightbox plugins know how to enhance it.
• Columns block + Image blocks. More layout control (different column widths, mixing images with text), but you have to set alt text and links on each Image block individually, and lightbox plugins may not detect them as a gallery.

Use Gallery for “here are 12 photos from the event,” Columns + Image for “here is a feature with three product cards, each with its own image and caption.”

The Media Library#

The Media Library (Media > Library in the admin) is the central registry of every file you have uploaded to your site. Every image you upload through the Image block, the Gallery block, or drag-and-drop also appears here automatically. You can also upload directly to the Media Library without inserting the image into a post, which is useful when:

• You want to upload many images at once for a future post.
• Someone else is going to write the post and you are just providing assets.
• You want to organize images before deciding where they go.

To upload directly: Media > Add New, then drag files into the upload area or click Select Files. Each file is processed (resized into the standard sizes, alt text field exposed, attached to no specific post until you use it) and listed in the library.

How WordPress generates image sizes

WordPress does not just store the file you uploaded. It generates several resized versions automatically:

• Thumbnail. 150×150 by default, cropped to a square. Used for archive previews and admin thumbnails.
• Medium. Up to 300×300, scaled (not cropped) so the longer side fits.
• Large. Up to 1024×1024, scaled.
• Full. The original file you uploaded, untouched.

Themes can register additional sizes – a “post-thumbnail” 800×450 size for featured images, a “hero” 1920×600 size for full-width banners. The block editor’s size picker in the Image block’s right sidebar shows whichever sizes are registered.

This matters because WordPress serves the smallest version that is large enough for the display context. A 200px-wide thumbnail in a sidebar widget should not be served as the original 4000×3000 photo – the thumbnail size exists precisely so the browser downloads 30KB instead of 4MB. Picking the right size in the block sidebar (and trusting srcset to pick the right one for high-DPI screens automatically) is one of the cheapest performance wins on any WordPress site, and how to speed up WordPress covers the full image-optimization toolkit including modern formats like WebP and AVIF.

Configure the default sizes

Settings > Media in the admin lets you change the dimensions for thumbnail, medium, and large. These changes only affect images uploaded after the change – existing images keep their old sizes unless you regenerate them with a plugin like Regenerate Thumbnails.

The “Crop thumbnail to exact dimensions” checkbox forces square thumbnails. Turn it off if you want thumbnails that preserve aspect ratio (the default), turn it on if you want a uniform grid.

Featured images#

A featured image is a single image associated with a post that themes display in specific places: the archive listing, the top of the single-post template, social-sharing meta tags, and sometimes in widgets like “Recent Posts.” It is conceptually separate from the images embedded inside the post content.

To set one:

1. With the post or page open in the editor, look at the right-side Document panel.
2. Find the Featured image section. Click Set featured image.
3. Pick or upload an image in the dialog that appears.
4. Click Set featured image to confirm.

The featured image now appears wherever the theme uses it – typically at the top of the post on the front end, and as the thumbnail in archive listings.

A few things worth knowing:

• The featured image is also what gets shared on social media. When someone pastes your post URL into Facebook, LinkedIn, or Twitter, the featured image (via the og:image meta tag) is what shows up. SEO plugins like Yoast and Rank Math let you override this with a custom social image if needed.
• Themes decide the display. Some themes show the featured image as a hero banner. Some show it inline at the top of content. Some do not show it at all on single posts. Test the display before assuming it will look right.
• Aspect ratio matters. A featured image that is portrait orientation (taller than wide) will look strange in a theme that expects 16:9 landscape. Pick consistent ratios for the site to look polished.

Replacing an image everywhere it is used#

A common problem: you have used the same image (a logo, a product photo, a screenshot) across 30 posts, and you need to swap it for an updated version. Editing each post individually is tedious. There are two paths.

WordPress core’s built-in Replace Media

In current WordPress versions, the Media Library’s Edit media screen has a Replace media button when the file is properly attached to your library. Click the image in Media > Library, click Edit more details (or the link to the full edit screen), and look for the Replace media option. Upload a new file – WordPress replaces the underlying file at the same URL, and every post using that URL automatically shows the new image without any post edits.

This is the cleanest path for a one-off swap on a current WordPress site.

Enable Media Replace plugin

For older WordPress installs without the built-in option, or for more control over how the replacement happens (replace and rename, update all references in post content, choose a different upload date), the Enable Media Replace plugin from ShortPixel is the standard choice. It has 600,000+ active installs, an active maintenance schedule, and adds the Replace Media interface to every Media Library item.

The plugin offers two modes:

• Just replace the file. Upload a new file of the same type (JPG for JPG, PNG for PNG). The URL stays the same; every post using the image shows the new version automatically.
• Replace and use the new file name. The old URL is replaced with the new one, and the plugin updates all post content that referenced the old URL to point to the new one.

The first mode is non-destructive and almost always the right choice. The second is useful when you are renaming files for SEO (a generic IMG_4827.jpg becoming red-leather-handbag-front.jpg ) but bears the risk that any external sites linking to the old URL will break.

Common upload errors#

Image uploads fail for predictable reasons. Here is what each error actually means.

“HTTP error” with no other detail

The most-reported and most-frustrating WordPress upload error. “HTTP error” is a generic message WordPress shows when it could not process the file – it does not actually mean the HTTP layer failed. The real causes, in rough order of frequency:

1. The file is larger than the upload limit. PHP enforces both upload_max_filesize and post_max_size . A 6MB photo against a 2MB limit fails as “HTTP error.” How to increase the maximum upload file size in WordPress covers raising the limits in php.ini , wp-config.php , and the control panel.
2. The PHP memory_limit is too low for image processing. Resizing a 24-megapixel JPEG into multiple thumbnail sizes can use 256MB+ of memory. If memory_limit is set lower than that, the resize step fails and the upload appears to fail with “HTTP error.”
3. The image editor library (GD or Imagick) is not installed or is broken. WordPress needs one of these PHP extensions to generate the resized versions. If neither is available, uploads fail silently.
4. Browser session timeout during a slow upload. A large file on a slow connection can trip the timeout before the upload finishes. Smaller files or a faster connection.
5. A security plugin or mod_security rule is blocking the file. Some WAF rules flag image uploads (especially those with EXIF data containing unusual characters) as suspicious and block them at the web server layer.

“The uploaded file exceeds the upload_max_filesize directive”

Direct version of cause #1 above. The browser knows the file is too big before the upload completes. Same fix.

“Sorry, this file type is not permitted for security reasons”

WordPress restricts what file types non-administrators can upload. Common image formats (JPG, PNG, GIF, WebP, AVIF, SVG-with-restrictions) are all allowed by default, but some hosts disable types like SVG by default because of XSS risk. To allow SVG, install a plugin like Safe SVG that sanitizes the file on upload, or have an administrator add the MIME type to the allowed list.

Upload finishes but the image does not appear

Almost always a permissions issue. WordPress wrote the file but cannot read it back, or it cannot write the resized versions. Check that wp-content/uploads/ is owned by the user PHP runs as (typically www-data , apache , or nginx ), and that directory permissions are at least 755 with files at 644.

Common mistakes#

• Uploading the original 24-megapixel photo straight from the camera. A 4000×3000 image at 300dpi is roughly 6MB – completely overkill for any web use. Resize before upload to the largest size your theme actually uses (usually 1920px wide is the upper limit), or let a plugin like Resize Image After Upload do it automatically.
• Setting the displayed size in the block sidebar but uploading the full image anyway. WordPress generates resized versions, but the original full-size file is still uploaded and stored. Resize before upload to save disk space and reduce backup size.
• Forgetting alt text. Every image needs alt text for accessibility, SEO, and visitors with images turned off. Decorative images get an empty alt="" (which is different from no alt attribute at all).
• Inserting an image from a URL on a third-party site. WordPress can do it, but if the source site changes the URL or removes the image, your post breaks. Always upload to your own Media Library.
• Not using a CDN for image-heavy sites. A photo blog or e-commerce site with 200 product images per page benefits enormously from a CDN serving the images from edge locations. The performance gain is large, the cost is small.
• Skipping image compression. WordPress does not compress aggressively by default. A plugin like ShortPixel, Smush, or EWWW Image Optimizer cuts image weight by 30-70% without visible quality loss.
• Using GIF for animations on a content-heavy page. GIFs are 10x larger than the equivalent MP4 or WebM. For animated visuals, use video, not animated GIF. How to add animated GIFs to WordPress covers both: the GIF route for the cases where it is the right choice, and the MP4/WebM Video block setup that gives you GIF-like playback at a fraction of the size.
• Uploading PDFs and PSDs to the Media Library and forgetting them. Non-image files in the Media Library accumulate over years and can balloon disk usage. The Media Library lets you filter by file type – audit periodically.

How Hostney handles image uploads#

Image upload limits and PHP memory are the most common reasons “HTTP error” shows up on shared hosting, and both are configurable on Hostney without leaving the control panel.

The default PHP limits are set generously for image-heavy sites: upload_max_filesize and post_max_size are both well above the WordPress default, and memory_limit is sized to handle thumbnail generation on large source images. If you need to raise them further (for example, to accept 50MB raw camera files), they are available under Hosting > PHP Manager > Variables for any value the platform allows.

GD and Imagick are both installed in the PHP container, so WordPress’s image-resizing pipeline works out of the box without needing to enable an extension. The wp-content/uploads/ directory is created with the correct ownership and permissions during account provisioning, so the “upload finishes but the image does not appear” permissions class of bug should not happen on a fresh account.

For sites that grow into hundreds of megabytes of images, the file manager (covered in the file manager guide) lets you browse, bulk-download, or selectively remove uploads without SFTP. The full performance picture – cache, HTTP/3, modern image formats – is in how to speed up WordPress.

Summary#

The Image block is the right tool for almost every single-image situation, the Gallery block is for sets of images shown together, drag-and-drop is the fastest workflow when you have the file on your desktop, and the Media Library is where everything lives once uploaded. Featured images are a separate concept – one image per post, used by themes for archives, social shares, and post headers. WordPress generates resized versions of every upload (thumbnail, medium, large, full) automatically, and the right size for the display context is the difference between a fast page and a slow one. Most upload errors trace to PHP limits, memory, or the image editor library – “HTTP error” almost never means HTTP – and raising the limits in your control panel fixes the majority of them. Always set alt text, always pick the right size for the context, and resize giant camera files before upload to keep the Media Library lean.