The WordPress Media Library

An upload is not a file, it is a set of files plus a database record. WordPress stores the original, generates several resized copies, and creates an attachment post to hold the title, alt text, caption and description. Understanding that shape explains almost every media library question.

What happens when you upload an image

1. The original goes into wp-content/uploads/YYYY/MM/.
2. WordPress generates the registered sizes — thumbnail, medium, large, plus whatever the theme and plugins register.
3. An attachment post is created, holding the metadata and pointing at the files.
4. srcset markup is generated from those sizes so browsers pick an appropriate one.

Two consequences worth knowing. Your uploads folder is several times the size of your originals, which is normal and is why backup sizes surprise people. And each attachment has its own URL — an attachment page — which is a thin page search engines can index. Most SEO plugins offer to redirect those to the parent post; it is usually worth doing, and attachment pages are also a common cause of slugs mysteriously gaining a number, as permalinks not working describes.

Upload at the right size

The most valuable habit, and the cheapest:

• Do not upload camera originals. A 6000px photo so WordPress can display 1200px wastes storage, slows every regeneration and does nothing for quality.
• Upload at roughly twice the largest display size, which covers high-density screens.
• Compress before uploading, then let an optimisation plugin handle the rest — how to optimise images in WordPress.
• Export as sRGB, or colours shift in browsers.
• Use the right format: photographs as JPEG or a modern equivalent, logos and diagrams as SVG or PNG.

If images look soft after upload, the cause is usually a size mismatch rather than compression — how to fix blurry images in WordPress.

Name and describe files before uploading

Metadata is far easier to get right on the way in than to repair later.

• Filenames should describe the image in words, with hyphens. oak-dining-table-walnut.jpg, not IMG_4471.jpg. The filename becomes part of the URL and cannot be changed afterwards without breaking every reference.
• Alt text describes the image for people who cannot see it. It is an accessibility requirement first and an SEO benefit second. Decorative images take empty alt text, not a keyword.
• Title, caption and description are optional. Captions display; titles and descriptions usually do not.

Doing this at upload time for a hundred images costs minutes. Doing it retrospectively for two thousand is a project.

Organisation, and its trade-off

Core files uploads into year and month folders and offers no folder interface. Options:

• Search and filter by date, type and attachment status — adequate for most sites.
• A media folder plugin, giving virtual folders. Useful on large libraries, and it becomes a dependency: the folder structure lives in that plugin's data, so removing it loses the organisation, not the files.
• Discipline in filenames — a consistent prefix per project or product achieves much of what folders would, with no dependency.

Replacing a file

Uploading a new version creates a second attachment; it does not update the first. Every page still shows the old one.

To genuinely replace an image, either use a replace-media plugin that overwrites the file in place and keeps the URL, or upload the new one and update each usage deliberately. Replacing in place keeps the URL — which is what you want for a logo — but caches will keep serving the old file until purged, so purge afterwards: how to clear the WordPress cache.

Cleaning up

Libraries accumulate: test uploads, images from a deleted page, five generated sizes from a theme you no longer run.

Regenerating sizes after a theme change removes nothing but creates the sizes the new theme needs. Old sizes from the old theme remain until deleted separately.

Unused-media scanners need real caution. They find references in post content and featured images, and they routinely cannot see images referenced by:

• a page builder's stored data;
• a custom field;
• a theme option such as a logo or a background;
• a slider, a gallery plugin, or CSS.

So the "unused" list contains files that are in use. Take a backup first, spot-check a sample, and delete in small batches rather than accepting the whole list.

Offloading to a CDN or object storage

On an image-heavy site, serving media from a CDN or moving it to object storage removes the load from your server and puts files nearer the visitor. Two things to verify before committing:

• URL rewriting is reversible. If the plugin rewrites URLs in post content rather than at render time, you are locked in.
• Backups include the media. Once files leave your server, your host's backup no longer contains them — that is now your responsibility.

A CDN in front of your own origin is the simpler version and gets most of the benefit; see Cloudflare and WordPress.

Common mistakes

• Uploading camera originals, then wondering why the site is slow and the backups are enormous.
• IMG_4471.jpg, permanently, in the URL.
• No alt text, which is an accessibility failure with a legal dimension in some jurisdictions.
• Uploading a replacement and assuming pages will update.
• Trusting an unused-media scan and deleting images a page builder was using.
• Letting every plugin register new image sizes, multiplying the files generated for every future upload.

Verify

Upload one image and check that it lands in the expected folder, generates the sizes your theme uses, emits srcset in the rendered page, and displays at a sensible file size on a phone. Then check that your backup actually contains wp-content/uploads — a database-only backup restores a site with no images at all.