WordPress Media Library: File Types, Folders & Fixes (2026)

The WordPress media library is the central hub for every file on your site — images, PDFs, videos, audio. It is one of the first things new WordPress users encounter and one of the most underestimated tools for experienced site owners. Get it right and your site stays fast, accessible, and easy to maintain. Ignore it and you end up with thousands of unnamed files, missing alt text, and broken images that took minutes to track down.

This guide covers everything: what the media library actually is, which file types WordPress accepts by default, how grid and list views work, why you need a plugin to add folders, how alt text and metadata are stored, the most common problems and their fixes, and how to export your media library when you need to move or back it up.

What Is the WordPress Media Library?

The WordPress media library (found at Media → Library in your dashboard) is the built-in asset manager that stores and organizes every file you upload to your WordPress site. According to the official WordPress documentation, media consists of images, video, recordings, and files that you upload and use in your posts and pages.

Uploads land in your server’s wp-content/uploads/ folder, organized by year and month by default (e.g., wp-content/uploads/2026/06/). The library screen gives you a visual interface to browse, edit, and delete those files without touching the server directly.

Every uploaded file becomes a WordPress attachment — a special post type stored in the database alongside its metadata: filename, MIME type, file size, dimensions (for images), alt text, title, caption, and description.

Supported File Types

WordPress maintains an allowlist of accepted file types for security reasons. Uploading a file outside this list produces the error: “Sorry, this file type is not permitted for security reasons.”

Here are the file types WordPress accepts by default, as documented in the WordPress Codex:

Category	Formats
Images	`.jpg` `.jpeg` `.png` `.gif` `.ico`
Documents	`.pdf` `.doc` `.docx` `.ppt` `.pptx` `.pps` `.ppsx` `.odt` `.xls` `.xlsx` `.psd`
Audio	`.mp3` `.m4a` `.ogg` `.wav`
Video	`.mp4` `.m4v` `.mov` `.wmv` `.avi` `.mpg` `.ogv` `.3gp` `.3g2`

What is not supported by default: .svg, .webp (note: WordPress 5.8 added native WebP upload support; WebP as the default format for generated sub-sizes was proposed for 6.1 but reverted before release, so core still generates sub-sizes in the original format unless a plugin enables WebP), .zip, .xml, .csv, .ai, and any executable formats. To enable additional types, use a plugin such as File Upload Types by WPForms or add a upload_mimes filter in your theme’s functions.php.

Your hosting provider may impose its own limits on file size or permitted types regardless of WordPress’s allowlist. If uploads fail for permitted file types, check your host’s PHP settings (upload_max_filesize, post_max_size).

Grid View vs. List View

The media library offers two layouts. You switch between them using the icons in the top-left of the Media Library screen.

Grid View

Grid view displays thumbnails of images and icons for non-image files in a responsive grid. It is the default. Clicking any item opens the Attachment Details panel on the right, where you can edit alt text, title, caption, description, and copy the file URL — all without leaving the library. Changes save automatically.

You can filter the grid by media type (Images, Audio, Video, Unattached) and by upload date.

List View

List view shows files in a sortable table with columns for thumbnail, file name, author, the post or page the file is attached to, and upload date. It is more practical for bulk operations: select multiple items, then use the Bulk Actions dropdown to delete them permanently.

List view also exposes an Attach action for files that are not associated with any post or page — useful for cleaning up orphaned uploads.

Which should you use? Grid view is faster for browsing images. List view is better for audits — spotting unattached files, checking authors, and running bulk deletions.

Organizing Media: Why Folders Require a Plugin

This is where many WordPress users are surprised: the WordPress media library has no native folder system. Out of the box, your library is a flat list sorted by upload date. You can filter by type and date, but you cannot create folders or drag files into categories.

The underlying reason is architectural. WordPress stores all attachment metadata in the wp_posts table using the attachment post type. Folder hierarchies are not part of the default schema.

To add folders, you need a plugin. Popular options include:

FileBird — drag-and-drop folder management; stores folders in a custom table
Real Media Library — tree-based folders with bulk move
HappyFiles — lightweight alternative with a similar drag-and-drop interface

These plugins do not move the physical files on the server. They store folder assignments in the database and filter the library display accordingly. If you uninstall the plugin, your files remain in wp-content/uploads/ exactly as they were — only the virtual folder structure is lost.

For most sites with fewer than a few hundred media items, date-based filtering combined with consistent file naming is enough. Folders become important for media-heavy sites like photography portfolios, news sites, or WooCommerce stores with large product image libraries.

Alt Text and Metadata

Every image in the WordPress media library can carry four text fields:

Field	Purpose	Stored as
Alt Text	Describes the image for screen readers and search engines	`_wp_attachment_image_alt` post meta
Title	Shown in attachment pages and galleries	`post_title` in `wp_posts`
Caption	Short explanatory text shown below images in posts	`post_excerpt` in `wp_posts`
Description	Longer description for the attachment page	`post_content` in `wp_posts`

Alt text matters most. It is read by screen readers, indexed by search engines, and displayed when an image fails to load. The WordPress documentation explicitly notes it is used for accessibility. Despite its importance, missing alt text is one of the most common issues on WordPress sites — especially for images added quickly through the block editor.

To edit alt text in bulk, you must either go through each attachment individually in the media library or use a dedicated plugin. This is where AI-driven workflows (covered below) add real value.

Common Media Library Issues and Fixes

Media library not loading

The library screen loads via a REST API request. If it shows a blank grid or spinner that never resolves, the most common causes are:

A security plugin blocking the wp/v2/media endpoint
A JavaScript conflict (check the browser console for errors)
An incompatible plugin or theme — deactivate plugins one by one to isolate the cause
A misconfigured permalink structure — go to Settings → Permalinks and save (flushes rewrite rules)

Can’t delete media

Files that are set as featured images on posts cannot be deleted from the library while that relationship exists. WordPress will let you click Delete Permanently, but the file remains visible because it is still referenced. Remove the featured image from the post first, then delete from the library.

When you click “Delete Permanently” in the media library, the file is removed from the server. WordPress does not show a recoverable Trash folder for media in the default admin interface, though the underlying system supports trashing attachments when MEDIA_TRASH is enabled.

Upload fails silently

If an upload stops without an error message, the most common culprit is php.ini limits. Check upload_max_filesize and post_max_size with your host. Another common cause is insufficient disk space or directory permissions on wp-content/uploads/.

Broken image URLs after migration

When migrating a WordPress site, images can break if the domain or directory path changes. The _wp_attached_file and _wp_attachment_metadata post meta values store relative paths. If the uploads_url setting differs, all attachment URLs break. The standard fix is to run a search-replace on the database — tools like WP-CLI’s search-replace command handle this reliably.

Exporting Your Media Library

WordPress does not include a native “export media library” feature. The built-in exporter (Tools → Export) can export posts and pages but downloads media only as XML with file URLs — it does not package the actual files.

Practical approaches to export media library WordPress:

FTP/SFTP download — Connect to your server and download the entire wp-content/uploads/ folder. This is the most complete method and preserves the year/month directory structure.
cPanel File Manager — If your host provides cPanel, you can compress the uploads folder and download the archive.
WP-CLI — wp post list --post_type=attachment --field=guid gives you a list of all registered attachment URLs; combine with shell scripting to download or inventory them.
Duplicator or All-in-One WP Migration — These migration plugins export your full site including media as a single package.

When exporting for a site migration specifically, the database export is equally important — without it, WordPress will not know about the files even if they exist on the server.

Managing Media with AI via Easy MCP AI

If you manage a WordPress site with hundreds or thousands of media items, manual audits are slow. Finding every image without alt text, or renaming files by convention, or checking whether images are attached to any published content — these tasks are repetitive and easy to automate.

Easy MCP AI is a free, open-source WordPress plugin that turns your WordPress site into a fully compliant remote MCP server. It exposes 214 tools (96 core WordPress tools, 80 plugin tools, and 38 data integrations) to any MCP-capable AI client — Claude, ChatGPT, Cursor, and 13 others.

The 96 core WordPress tools include media management. That means an AI client connected through Easy MCP AI can:

List all media files — query your library by type, date, or attachment status
Read and update attachment metadata — including alt text, title, caption, and description
Find images with missing alt text — surface accessibility gaps across your entire library
Suggest alt text — describe each image and generate contextually relevant alt text
Identify unattached media — find uploads not linked to any post or page

Setup is: install Easy MCP AI → copy your MCP server URL from Easy MCP AI → Dashboard → add it as a custom connector in your AI client → authorize via OAuth. Everything stays on your own server. Credentials are encrypted AES-256-GCM with per-provider HKDF-derived keys — nothing is sent to third parties until you actively run a command.

For more on connecting AI to your full WordPress workflow, see Claude MCP WordPress.

Example Prompts After Connecting

“List all images in my media library that have no alt text.”
“For each image without alt text, suggest a concise, descriptive alt text based on the filename and any post it is attached to.”
“Find all media items uploaded more than two years ago that are not attached to any post or page.”
“Update the alt text for attachment ID 847 to: ‘Team photo taken at the 2025 company retreat in Barcelona.’”

Key Facts

The WordPress media library stores files in wp-content/uploads/ organized by year and month
Default accepted formats cover images (jpg, png, gif, ico), documents (pdf, doc, docx, xls, xlsx, psd, odt, ppt/pps formats), audio (mp3, m4a, ogg, wav), and video (mp4, mov, wmv, avi, ogv, mpg, 3gp, 3g2)
WordPress has no native folder system — folders require a third-party plugin like FileBird or Real Media Library
Attachment metadata (alt text, title, caption, description) is stored in the WordPress database, not in the file itself
Alt text is stored as _wp_attachment_image_alt post meta and matters for both accessibility and SEO
Clicking “Delete Permanently” removes the file from the server; WordPress does not expose a recoverable Trash for media in the default admin interface (requires MEDIA_TRASH)
Exporting the media library requires FTP/SFTP access or a migration plugin; the built-in exporter does not package files
Easy MCP AI’s 96 core WordPress tools include media management, enabling AI-driven alt text audits and updates

Conclusion

The WordPress media library is more capable than it looks — and more limited than many users expect. It handles a broad range of file types, gives you two views optimized for different workflows, stores rich metadata per file, and integrates directly with the block editor. Its main gaps — no native folders, no bulk alt text editor, no built-in export — are all solvable with the right plugins or workflows.

If your library has grown large enough that manual audits are impractical, connecting an AI assistant through Easy MCP AI is a concrete way to surface missing alt text, identify orphaned uploads, and update metadata at scale — through conversation rather than clicking through hundreds of attachment detail panels.

→ Get Easy MCP AI from the WordPress plugin directory