Media Library

Every uploaded file becomes an attachment: a row in the posts table with post_type set to attachment, the file’s MIME type in post_mime_type, the title in post_title, the caption in post_excerpt and the description in post_content. The file itself goes to wp-content/uploads/ (in YYYY/MM/ sub-folders when "Organize my uploads into month- and year-based folders" is checked under Settings > Media, the default). Three post meta keys complete the record: _wp_attached_file (the path relative to the uploads directory), _wp_attachment_metadata (a serialized array with width, height, every generated size, original_image and EXIF-derived image_meta) and _wp_attachment_image_alt (the alternative text).

The table layout is described in Database Schema. An attachment may have a parent post (post_parent): an image uploaded while editing a post is attached to it, and one uploaded from the Library is unattached. Attachment is only bookkeeping. The same image can appear in any number of posts, and deleting the parent does not delete the file.

Uploading requires the upload_files capability, which Authors, Editors and Administrators have and Contributors do not. Editing or deleting someone else’s file requires edit_others_posts / delete_others_posts, so an Author manages only their own uploads. The roles are described in Users, Roles and Profiles.

Media > Library (upload.php) lists every attachment, and Media > Add Media File (media-new.php) is a drag-and-drop upload page that shows the maximum upload size. The Library has two views, switched with the icons above the list. The grid view shows thumbnails, filters by type (Images, Audio, Video, Documents, Spreadsheets, Archives, Unattached) and by month, a live search and Bulk select; clicking an item opens the Attachment details dialog, which saves changes automatically and moves between items with the arrow keys. The list view is a sortable table (File, Author, Uploaded to, comments, Date) with Screen Options for items per page, row actions (Edit, Delete Permanently, View, Copy URL, Download file) and Attach for unattached files.

The Attachment details dialog and the full Edit Media screen (post.php?post=<id>&action=edit) show the upload date and author, the post it is attached to, file name, MIME type, size and dimensions, and the editable fields: Alt Text, Title, Caption and Description. File URL is read-only, with Copy URL to clipboard and Download file next to it. Audio files add Artist and Album fields read from the file’s tags.

Deleting is permanent. Attachments have no trash unless MEDIA_TRASH is defined as true in wp-config.php (it defaults to false); with it, the Library gains a Trash filter and Move to Trash replaces Delete permanently. Deleting an attachment removes the original file, every generated size and the attachment row. Content that still refers to the file keeps a broken image, because WordPress does not track where an attachment is used.

WordPress decides what may be uploaded in two steps. First, the file’s extension must be in the list returned by get_allowed_mime_types(). Second, wp_check_filetype_and_ext() reads the file’s real content type and rejects a file whose content does not match its extension (an HTML file renamed to .jpg, for instance). A rejected file produces "Sorry, you are not allowed to upload this file type."

The list is not fixed. get_allowed_mime_types() starts from wp_get_mime_types() (98 entries in 7.1), always removes swf and exe, removes htm|html and js for users without the unfiltered_html capability, and then passes the result through the upload_mimes filter. On a single site only Administrators and Editors have unfiltered_html; on Multisite only Super Admins do, and each site’s list is further limited by Network Admin > Settings > Upload file types (the upload_filetypes network option). Defining ALLOW_UNFILTERED_UPLOADS as true lets Administrators (Super Admins on Multisite) upload any type; it is a debugging switch, not a production setting.

The following command prints the effective list for two users of the Lumen Press site, the Administrator lp_admin (user 1) and the Author lp_author (user 2):

Source: Code Reference: get_allowed_mime_types()

Without any filter, an Administrator may upload 96 types: images (jpg/jpeg/jpe, gif, png, bmp, tif/tiff, webp, avif, ico, heic, heif, heics, heifs), video (mp4/m4v, mov, webm, ogv, mkv, avi, mpeg, wmv, flv, 3gp, 3g2 and a few older Windows formats), audio (mp3/m4a/m4b, aac, wav, ogg/oga, flac, mid, wma, mka, ra), text (txt, csv, tsv, ics, rtx, css, vtt, dfxp, plus htm/html and js for unfiltered_html users), documents (pdf, rtf, the Microsoft Office, OpenDocument and Apple iWork families, oxps, xps, OneNote, WordPerfect) and archives and other files (zip, tar, gz, rar, 7z, psd, xcf, class).

Source: Code Reference: wp_get_mime_types()

The list printed in older books predates WebP (5.8), AVIF (6.5) and HEIC (6.7) and reads as if it were fixed. In a current install it is longer, it depends on the user’s capabilities, and on Multisite it depends on the network setting; get_allowed_mime_types() or a test upload is the authoritative answer. EPUB and SVG are absent by default, which matters for a publisher.

Source: Make WordPress Core: WordPress 6.5 adds AVIF support

The HEIC conversion depends on the PHP process that handles the upload. In the official images, the Apache image’s Imagick lists HEIC and HEIF among its formats, but the wordpress:cli image’s Imagick does not, so a wp media import of a .heic file from that container creates an attachment with no sizes and no metadata. Running WP-CLI inside the web container gives the expected result. The Apache image has no WP-CLI, so the first three lines copy the wp binary from the CLI image into it. The attachment keeps the image/heic MIME type, its main file and every size are JPEGs, and original_image names the HEIC file:

Source: Make WordPress Core: Automatic conversion of HEIC images to JPEG in WordPress 6.7

The conversion is driven by the image_editor_output_format filter, whose default mapping in 7.1 sends image/heic, image/heif, image/heic-sequence and image/heif-sequence to image/jpeg. The same filter can make WordPress generate WebP or AVIF files from JPEG uploads. The "full" file and every size are then written as AVIF, the post MIME type stays image/jpeg, and the uploaded JPEG is kept and named in original_image:

Importing a 1200 × 800 JPEG with that filter active and printing the MIME type, main file and sizes gives the output below; original_image is launch-night-1.jpg:

Source: Code Reference: image_editor_output_format hook

Core does not serve AVIF or WebP with a JPEG fallback through <picture>; all browsers in current use decode WebP and AVIF, and a site with older clients leaves the default in place. Core also does not convert images that were uploaded before a filter was added.

For each uploaded image WordPress creates resized copies. Three are set under Settings > Media, and three more are registered by core without a screen:

Themes and plugins add their own with add_image_size(). A size is only generated when the original is larger than its box; WordPress never upscales. wp media image-size lists what is registered on the Lumen Press site, including the lp-book-cover size from the must-use plugin:

Source: WP-CLI Commands: wp media image-size

Every registered size costs disk space and upload time for every image, whether the site displays it or not. Themes that register many sizes, and plugins that each add a few, are a common reason for slow uploads and large backups.

Until 7.0 every image size was produced on the server by GD or Imagick, which is where large phone photos ran into memory_limit, max_execution_time and missing codecs. WordPress 7.1 moves that work into the browser when it can. @wordpress/vips, a WebAssembly build of libvips running in a Web Worker, compresses, resizes, rotates according to EXIF, converts formats and generates every registered size before upload. The server then receives finished files.

How an upload travels on that path:

Because every size is its own request, a dropped connection loses one file, not the batch. Failed requests are retried automatically with exponential backoff, uploads pause when the browser goes offline and resume when it reconnects, and the editor shows progress per file. This is the "upload retry" of the 7.1 release.

The maximum upload size shown on Add Media File is wp_max_upload_size(), the smaller of PHP’s upload_max_filesize and post_max_size, passed through the upload_size_limit filter. Returning a larger value from the filter changes the number shown but not what PHP accepts; raising the limit means changing PHP (and the web server’s request body limit, client_max_body_size on nginx). The server side, including the nginx and .htaccess variants and what happens when each limit is exceeded, is described in Requirements and Hosting.

The official wordpress Docker image ships PHP’s defaults, upload_max_filesize = 2M and post_max_size = 8M, so a fresh container accepts nothing larger than 2 MB, less than many phone photos. Lumen Press mounts an extra ini file:

Source: PHP Manual: Description of core php.ini directives

The file is mounted into the official image’s PHP configuration directory, here in the wordpress service of the Compose file from Local Development Environments, next to the must-use plugin of this page:

Source: Docker Hub: wordpress (official image)

After the change, size_format( wp_max_upload_size() ) reports 64 MB in a request served by Apache. With client-side processing, sub-sizes arrive as separate, smaller requests, but the original file still has to fit the limit. On Multisite, Network Admin > Settings adds a lower Max upload file size (in KB) and a per-site upload space quota on top of PHP’s limits.

Alternative text is what screen readers announce and what appears when an image fails to load. WordPress stores it in two places, and the difference explains most "I fixed the alt text but the page did not change" reports:

Good practice, following the W3C’s alt decision tree: describe what the image conveys in its context ("Cover of The Lighthouse Keeper: a lighthouse on a cliff at dusk"), not "image of"; describe the destination when the image is a link; leave alt empty for purely decorative images (in the Image block, by leaving the field blank so that WordPress outputs alt=""); do not repeat a caption word for word. The same photo may need different alt text in different posts, which is what the block-level attribute is for. Accessibility for theme authors is covered in Theme Accessibility and Releasing and in general in Accessibility.

Images imported in bulk often arrive without alt text. wp media import --alt sets it on import, and a query finds the images still missing it so that an editor can fill them in:

Source: WP-CLI Commands: wp db query

Source: W3C WAI: An alt Decision Tree

The full list of corrections is in Where Older Books and Tutorials Are Outdated.