WordPress Media Library — How to Upload, Edit and Manage Images and Files

In this tutorial, you'll learn to use the WordPress media library — uploading and editing images, organizing files, managing file sizes, and following best practices for efficient media management on your WordPress site.

What You'll Learn

• How to access and navigate the Media Library in Grid view and List view
• How to upload files using drag and drop, the Add New button, and direct insertion into posts
• How to edit images: crop, rotate, flip, scale, and inline editing
• Which file types WordPress supports: jpg, png, webp, gif, pdf, docx, mp4, mp3
• How to set attachment details: title, caption, alt text, and description
• How to insert media into posts with proper alignment, size, and link settings
• How to detach and delete media from the library
• Media settings: image sizes and organizing by month
• How to manage file sizes for performance
• Popular bulk media management plugins

Why It Matters

Images and files make up the majority of your site's download size. Poorly managed media — huge file sizes, missing alt text, disorganized libraries — slows down your site, hurts Accessibility, and frustrates content editors who can't find the images they need. The WordPress Media Library is where you control all of this, and using it properly is essential for a fast, accessible, and maintainable website.

Real-World Use

A blog with 500 published posts has over 2,000 images in the Media Library. Without organization, finding a specific image takes 10 minutes. Without alt text, screen reader users get no context. Without proper sizing, the site loads 5 MB per page. With organized, optimized, and well-described media, the same site loads in 2 seconds and passes accessibility audits.

Learning Path

flowchart LR
    A[Page Templates] --> B[Media Library]
    B --> C[Image Optimization]
    B --> D[Comments & Discussion]
    C --> E[Performance Basics]

Accessing the Media Library

Navigate to Dashboard > Media to open the Media Library. You have two viewing options:

Grid View

The default view shows media items as a visual grid of thumbnails. Hover over an item to see quick actions: Edit, Delete Permanently, or View.

• Use the search bar to find files by name
• Filter by media type: Images, Audio, Video, Documents, Spreadsheets, etc.
• Filter by date uploaded
• Click "Add New" button to upload

List View

Click the "List View" icon (list icon next to the grid icon) to see items in a table with columns:

List view is better for sorting and bulk actions. Click column headers to sort by that column.

Uploading Files

Method 1: Drag and Drop

Open the Media Library or a post editor, and drag files from your computer directly into the browser window. WordPress uploads them immediately.

Method 2: Add New Button

In the Media Library, click the "Add New" button at the top. A file browser opens. Select one or more files and click "Open."

# You can also upload via WP-CLI
wp media import ~/images/photo.jpg --post_id=123 --title="My Photo"

Method 3: Inserting into Posts

When editing a post or page, click the plus (+) icon, select an Image block (or other media block), and choose:

• Upload — select a file from your computer
• Media Library — choose an existing file
• Insert from URL — paste an external image URL

Upload Settings

By default, WordPress stores uploads in:

/wp-content/uploads/2026/06/

Files are organized by year and month subdirectories. This keeps the file system manageable and helps with backup strategies.

// Change the uploads directory structure (in wp-config.php)
define('UPLOADS', 'wp-content/media');
// Or disable month-based organization
define('UPLOADS', 'wp-content/uploads');

Image Editing

WordPress includes a built-in image editor that lets you make basic adjustments without external software.

Accessing the Image Editor

1. Click any image in the Media Library
2. Click the "Edit Image" button
3. The editor opens with the image and a toolbar

Available Tools

Crop Details

When you click the Crop tool, you can:

• Drag to select a region
• Enter exact aspect ratio (e.g., 16:9, 4:3, 1:1)
• Enter exact pixel dimensions
• Apply the crop

// Crop an image programmatically
$image_id = 123;
$cropped = wp_crop_image(
    $image_id,     // Attachment ID
    50, 50,        // Crop x, y
    200, 200,      // Crop width, height
    400, 400       // New width, height
);

Saving Edits

• "Save" — overwrites the original image
• "Save as a new image" — creates a new attachment without modifying the original

Important: Editing an image in WordPress modifies the original file. If you need the original later, save as a new image instead.

File Types Supported

WordPress supports uploading these file types by default:

// Add additional file types (in functions.php)
add_filter('upload_mimes', 'custom_upload_mimes');
function custom_upload_mimes($mimes) {
    $mimes['svg'] = 'image/svg+xml';
    $mimes['json'] = 'application/json';
    return $mimes;
}

SVG Support

SVG is not allowed by default for security reasons. To enable it, add the filter above or install a plugin like "Safe SVG" that sanitizes SVG files before uploading.

Attachment Details

Each media item has metadata fields in the Attachment Details panel (open by clicking a file in the library):

Alt Text Best Practices

Alt text is the most important field for both accessibility and SEO:

<!-- Good alt text -->
<img src="pasta-dish.jpg" alt="A bowl of vegetarian pasta with tomato sauce and basil garnish on a wooden table">

<!-- Bad alt text -->
<img src="pasta-dish.jpg" alt="pasta">
<img src="pasta-dish.jpg" alt="image">
<img src="pasta-dish.jpg" alt="IMG_20240627_123456.jpg">

Write alt text that describes what the image shows and its context in the content. Avoid keyword stuffing — describe naturally.

Inserting Media into Posts

When you insert an image into a post, you have several settings:

Alignment

Size

WordPress generates several sizes for each uploaded image:

// Get available image sizes for an attachment
$sizes = wp_get_attachment_image_sizes($attachment_id, 'medium');
echo $sizes;
// Output: sizes="(max-width: 300px) 100vw, 300px"

Link To

Choose what happens when someone clicks the image:

• None — no link
• Media File — opens the full-size image in the browser
• Attachment Page — opens a WordPress page showing the image and its caption
• Custom URL — any external or internal link

Detaching and Deleting Media

Detaching

When you delete media from a post editor, you have two options:

• Detach — removes the image from the post but keeps it in the Media Library
• Delete permanently — removes the image from both the post and the Media Library

Deleting from the Library

To delete media permanently:

1. Select one or more files in the Media Library
2. Click "Delete Permanently" in the bulk actions dropdown
3. Confirm deletion

# Delete media via WP-CLI
wp media delete 123 456 --force

Warning: Deleting media from the library removes it from every post, page, and widget that uses it. The images become broken links on your site.

Media Settings

Configure media defaults at Settings > Media.

Image Sizes

You can change the default dimensions for thumbnail, medium, and large sizes:

Thumbnail size: 150 x 150 (crop to exact dimensions: [x])
Medium size: 300 x 300
Large size: 1024 x 1024

If you change these after images have been uploaded, existing images are not regenerated. Use the "Regenerate Thumbnails" plugin to create new sizes for old uploads.

// Set custom image sizes in functions.php
add_action('after_setup_theme', 'custom_image_sizes');
function custom_image_sizes() {
    set_post_thumbnail_size(200, 200, true);           // Crop to exact 200x200
    add_image_size('featured-large', 1200, 630, true); // Custom size
    add_image_size('card-image', 400, 300, false);     // Flexible height
}

Organizing by Month

The checkbox "Organize my uploads into month- and year-based folders" controls whether uploads go into /2026/06/ subdirectories or directly into /uploads/.

• Enabled: Cleaner organization, but harder to find files via FTP
• Disabled: All files in one directory, simpler FTP access but harder to manage for large sites

Managing File Sizes

Large images are the #1 cause of slow WordPress sites. Follow these guidelines:

// Limit uploaded image size in functions.php
add_filter('wp_handle_upload_prefilter', 'limit_upload_image_size');
function limit_upload_image_size($file) {
    $max_size = 2 * 1024 * 1024; // 2 MB
    $image_types = array('image/jpeg', 'image/png', 'image/gif', 'image/webp');

    if (in_array($file['type'], $image_types) && $file['size'] > $max_size) {
        $file['error'] = 'Image size must be less than 2 MB.';
    }

    return $file;
}

Image Compression Before Upload

Always compress images before uploading:

• Photos: Save as JPEG quality 80-85
• Graphics/UI: Save as PNG-8 or WebP
• Screenshots: PNG or WebP (better text clarity than JPEG)

Bulk Media Management Plugins

For sites with thousands of files, plugins add organization features:

Common Mistakes

1. Uploading images at full camera resolution: A 12 MP photo (4000x3000 pixels) displayed at 800x600 is 15x larger than needed. Resize images before uploading to match their display size.

2. Not filling in alt text: Every image needs alt text. Screen readers read it aloud. Search engines use it for image search. Missing alt text fails WCAG accessibility guidelines.

3. Using the "Delete Permanently" bulk action carelessly: Deleting media removes it from all posts. Always check which posts use a file before deleting.

4. Storing files that belong in folders: The Media Library has no built-in folders. Without a folder plugin, files accumulate into an unsearchable mess. Use a plugin or organize by date/month.

5. Uploading non-web formats (TIFF, BMP, PSD): These formats are not web-friendly. Users can't view them in browsers. Convert to JPEG, PNG, or WebP before uploading.

Practice Questions

1. What is alt text, and why is it important for accessibility and SEO?
2. If you change the Medium size from 300px to 400px in Settings > Media, do existing images change automatically?
3. What happens to posts if you delete an image from the Media Library that they use?

Challenge: Upload 10 images with different dimensions. Edit one image using the built-in editor (crop to 1:1 aspect ratio). Set alt text, title, and caption for each. Create a gallery post that displays them in a 3-column grid. Then verify that the HTML output includes proper alt text and responsive srcset attributes.

FAQ

Mini Project

Build a properly organized media library:

1. Upload 5 images (resized to max 1200px width, compressed under 200 KB each)
2. Set appropriate alt text, caption, title, and description for each
3. Create a gallery post with 3 images in a grid, one inline image aligned left, and one featured image
4. Edit one image using the built-in crop tool — save as a new image
5. Verify that all images have proper alt text and that the featured image appears correctly
6. Install one bulk media plugin and organize your files into at least 3 folders
7. Check each image's srcset in the browser's developer tools

What's Next

Now that you can manage media, master Image Optimization — understanding image sizes, WebP conversion, Lazy Loading, and compression for faster page loads. Then learn Comments and Discussion for community engagement.

For more on content, see Writing Posts and Managing Pages.