How to Use the WordPress Media Library

The WordPress media library is the central hub for managing every image, video, audio file, and document on your website. Whether you are building your first site or managing a large publication, mastering the media library saves time, improves site performance, and keeps your content organised. This guide walks you through everything you need to know, from basic uploads to advanced organisation techniques.

Understanding the WordPress Media Library Interface

Before you start uploading files, it helps to understand what you are looking at. The media library is accessible from the WordPress dashboard and presents your files in two viewing modes: Grid View and List View.

Grid View vs List View

Grid View displays your files as thumbnails, making it easy to browse images visually. List View shows files in a table format with columns for the file name, author, upload date, and the post it is attached to. Use List View when you need to find specific details quickly or bulk-manage files.

Filtering and Searching Your Media

At the top of the media library screen you will find several filtering options:

Media type filter — filter by images, audio, video, documents, or spreadsheets.
Date filter — narrow results by the month and year a file was uploaded.
Search bar — search by file name, title, caption, alt text, or description.

Using these filters together helps you locate any file within seconds, even in a library containing thousands of items.

How to Upload Files to the WordPress Media Library

WordPress makes uploading files straightforward. There are several methods depending on your workflow and the number of files you need to add.

Uploading via the Media Library Screen

Log in to your WordPress dashboard and navigate to Media > Add New.
Click the Select Files button or drag and drop files directly into the upload area.
Wait for the upload progress bar to complete. Each file will appear in the library once processed.
Click on any newly uploaded file to open the Attachment Details panel and add metadata.

Uploading from the Block Editor

Open or create a post or page in the WordPress block editor.
Add an Image, Video, or File block using the block inserter.
Click Upload to add a new file directly, or click Media Library to select an existing one.
The file is automatically added to the media library and inserted into your content.

Uploading via WP-CLI

If you manage WordPress from the command line, WP-CLI lets you import files directly into the media library without using the dashboard. This is especially useful for bulk imports or server-to-server migrations.

# Import a single image from the server into the media library
wp media import /var/www/html/uploads/my-photo.jpg --title="My Photo" --alt="A descriptive alt text" --post_id=42

# Import all JPG files from a directory
wp media import /var/www/html/uploads/*.jpg --porcelain

The --porcelain flag outputs only the attachment ID of each imported file, which is handy when scripting bulk operations.

Managing and Editing Media Files

Uploading files is only the beginning. Properly managing your media ensures your site remains fast, accessible, and easy to navigate.

Editing Attachment Details

Click any file in the media library to open the Attachment Details sidebar. Here you can edit:

Title — the internal name WordPress uses to identify the file.
Caption — text displayed below the image when it appears in content.
Alt Text — critical for accessibility and SEO; describes the image for screen readers and search engines.
Description — a longer text field for additional context, sometimes displayed on attachment pages.
File URL — the direct link to the file, useful for embedding or sharing.

Using the Built-in Image Editor

WordPress includes a basic image editor that allows you to make simple adjustments without leaving the dashboard:

Open the Attachment Details panel for any image.
Click the Edit Image button beneath the preview thumbnail.
Use the toolbar to crop, rotate, flip, or scale the image.
Select whether to apply changes to the All Image Sizes, Thumbnail only, or the Original image.
Click Save to apply your edits and return to the media library.

Deleting Media Files

To delete a file, hover over it in List View and click Delete Permanently, or open the Attachment Details panel and click the same link. Be aware that deleting a file from the media library removes it from all posts and pages where it is used — WordPress does not automatically replace broken references. Always check where a file is used before deleting it.

Organising Your Media Library

By default WordPress does not offer native folders for the media library, but there are effective ways to keep your files organised both within the dashboard and on the server.

Using Media Library Folders Plugins

Plugins such as FileBird, Real Media Library, and Enhanced Media Library add a folder or category system to the media library. With these plugins you can:

Create nested folder structures (e.g. Blog Images > 2024 > January).
Drag and drop files between folders.
Filter the media library by folder instantly.

Organising Files by Date on the Server

WordPress automatically organises uploaded files into folders by year and month on the server (e.g. wp-content/uploads/2024/06/). You can control this behaviour in Settings > Media. Uncheck Organize my uploads into month- and year-based folders if you prefer all files in a single uploads directory — though this is not recommended for large sites.

Adding Custom Taxonomy to Attachments

Developers can register a custom taxonomy for attachment post types, allowing category- or tag-based filtering natively. Add the following to your theme's functions.php file or a custom plugin:

// Register a custom taxonomy for media attachments
function wpguide_register_media_taxonomy() {
    register_taxonomy(
        'media_category',
        'attachment',
        array(
            'label'        => __( 'Media Category', 'textdomain' ),
            'rewrite'      => array( 'slug' => 'media-category' ),
            'hierarchical' => true,
            'show_admin_column' => true,
        )
    );
}
add_action( 'init', 'wpguide_register_media_taxonomy' );

After adding this code, a Media Category meta box appears on each attachment detail page, and a filter dropdown appears in the media library list.

Optimising Media for Performance

Large, unoptimised files are one of the most common causes of slow WordPress sites. The media library gives you the tools to control image sizes and formats, and plugins extend this further.

Configuring WordPress Image Sizes

When you upload an image, WordPress automatically generates multiple sizes based on settings in Settings > Media. The default sizes are:

Thumbnail — default 150 x 150 pixels (hard crop).
Medium — default max 300 x 300 pixels.
Large — default max 1024 x 1024 pixels.
Full — the original uploaded file.

You can adjust these dimensions, and themes or plugins may register additional sizes. To regenerate thumbnails after changing sizes, use the Regenerate Thumbnails plugin or the WP-CLI command wp media regenerate --all.

Using Image Optimisation Plugins

Plugins such as Smush, ShortPixel, and Imagify compress images automatically on upload without visible quality loss. Look for plugins that support:

Lossless and lossy compression modes.
Next-generation formats such as WebP and AVIF.
Lazy loading integration to defer off-screen image loading.
Bulk optimisation of existing library files.

Setting Maximum Upload File Size

WordPress respects the PHP upload limits set by your server. If you need to increase the maximum upload file size, add the following lines to your wp-config.php file or .htaccess:

// In wp-config.php — increase memory limit and upload size
define( 'WP_MEMORY_LIMIT', '256M' );

# In .htaccess — set PHP upload limits
php_value upload_max_filesize 64M
php_value post_max_size 64M
php_value max_execution_time 300
php_value max_input_time 300

After saving these changes, verify the new limit by going to Media > Add New and checking the text that reads Maximum upload file size.

Advanced Media Library Tips and Best Practices

Once you are comfortable with the basics, these advanced techniques will help you get even more out of the WordPress media library.

Always Fill In Alt Text

Alt text is one of the easiest wins for both accessibility and SEO. Every image on your site should have a descriptive alt text that accurately conveys the image content to users who cannot see it. Search engines also read alt text to understand what an image depicts, which can improve image search rankings.

Audit Unused Media Regularly

Over time, unused files accumulate and waste storage space. The plugin Media Cleaner or WP-Sweep can identify media files not attached to any post or page. Always back up your site before running a bulk delete of unattached media, because some themes and plugins reference files outside of the standard attachment system.

Use Descriptive File Names Before Uploading

WordPress uses the file name to auto-populate the title field. Rename files before uploading — blue-running-shoes-2024.jpg is far better than IMG_4892.jpg for both SEO and searchability inside the media library. Use lowercase letters and hyphens instead of spaces or underscores.

Restrict Media Library Access by User Role

On multi-author sites you may want authors to see only their own uploaded files. Add this snippet to your functions.php or a custom plugin to limit the media library by user role:

// Limit media library to files uploaded by the current user (for non-admins)
function wpguide_limit_media_library_access( $query ) {
    if ( ! current_user_can( 'manage_options' ) && 'attachment' === $query->get( 'post_type' ) ) {
        $query->set( 'author', get_current_user_id() );
    }
    return $query;
}
add_filter( 'ajax_query_attachments_args', 'wpguide_limit_media_library_access' );

Frequently Asked Questions

How do I increase the maximum upload file size in WordPress?

The upload limit is set by your PHP configuration. You can increase it by editing your wp-config.php or .htaccess file to raise upload_max_filesize and post_max_size values. Some hosting providers also let you change these limits from within their control panel under PHP settings.

Can I add folders to the WordPress media library?

WordPress does not include a native folder system for the media library, but plugins such as FileBird, Real Media Library, and Enhanced Media Library add full folder management with drag-and-drop functionality directly inside the dashboard.

How do I find images that are not being used on any page or post?

Use a plugin like Media Cleaner or WP-Sweep to scan your media library and identify unattached files. These tools show you which uploads are not linked to any content, so you can safely delete them and reclaim storage space.

Does deleting an image from the media library remove it from my posts?

Yes. When you permanently delete a file from the media library, WordPress removes the file from the server. Any post or page that displayed that image will show a broken image icon. Always check where a file is used — visible in the Attachment Details panel under Uploaded to — before deleting it.

Managing the WordPress media library efficiently makes a real difference to your site's speed, accessibility, and organisation. From uploading and optimising images to writing clean alt text and auditing unused files, each step covered in this guide contributes to a healthier, better-performing website. If you would rather handle these tasks conversationally without navigating menus, WP AI Agent lets you manage your WordPress media library and many other site tasks through simple natural-language AI chat — making WordPress management faster and more intuitive than ever.

How to Use the WordPress Media Library: A Complete Guide