import ScreenshotNumberReference from '/src/components/ScreenshotNumberReference.jsx';
import MediaLibraryProvidersList from '/docs/snippets/media-library-providers-list.md';
import StrapiAiCredits from '/docs/snippets/strapi-ai-credits.md'

Media Library#

The Media Library is the Strapi feature that displays all assets uploaded in the Strapi application and allows users to manage them.

:::strapi New Media Library available in
Strapi has completely reworked the Media Library UI, which is now available as a beta feature for the next few weeks before it becomes the default UI. You can try the beta by configuring the future.betaMediaLibrary property in the config/features file as follows:

module.exports = () => ({
  future: {
    betaMediaLibrary: true,
  },
});

export default () => ({
  future: {
    betaMediaLibrary: true,
  },
});

Restart your Strapi application after the configuration change. Set the property to false and restart Strapi to use the current stable version again.

The current page still describes the stable version of the Media Library. Over the next few weeks, the documentation will be updated to reflect the new features. In the meantime, you can .
:::

Configuration#

Some configuration options for the Media Library are available in the admin panel, and some are handled via your Strapi project's code.

Admin panel configuration#

In the admin panel, some Media Library settings are available via the Global Settings to manage the format, file size, and orientation of uploaded assets. It is also possible, directly via the Media Library to configure the view.

Configuring settings#

Path to configure the feature: Settings > Global Settings > Media Library.

1. Define your chosen new Media Library settings:

   Setting name	Instructions	Default value
   Generate AI captions and alt texts automatically on upload!	Enabling this option will turn on AI‑powered metadata generation	True
   Responsive friendly upload	Enabling this option will generate multiple formats (small, medium and large) of the uploaded asset. Default sizes for each format can be configured through the code.	True
   Size optimization	Enabling this option will reduce the image size and slightly reduce its quality.	True
   Auto orientation	Enabling this option will automatically rotate the image according to EXIF orientation tag.	False

2. Click on the Save button.

<ThemedImage
alt="Media Library settings"
sources={{
light: '/img/assets/settings/settings_media-library-2.png',
dark: '/img/assets/settings/settings_media-library-2_DARK.png',
}}
/>

Configuring the view#

Path to configure the feature: Media Library

1. Click on the button just above the list of folders and assets, on the right side of the interface.
2. Configure the Media Library view, following the instructions below:

   Setting name	Instructions
   Entries per page	Use the dropdown to define the number of assets displayed by default per page.
   Default sort order	Use the dropdown to define the default order in which assets are displayed. This can be overriden when sorting assets in the Media Library.

<ThemedImage
alt="Configure the view"
sources={{
light: '/img/assets/media-library/media-library_configure-the-view.png',
dark: '/img/assets/media-library/media-library_configure-the-view_DARK.png',
}}
/>

Code-based configuration#

The Media Library is powered in the backend server by the Upload package, which can be configured and extended through providers.

Providers#

If you need to install other providers or create your own, please refer to the following guide:

Available options#

When using the default upload provider, the following specific configuration options can be declared in an upload.config object within the config/plugins file. All parameters are optional:

Example custom configuration#

The following is an example of a custom configuration for the Upload plugin when using the default upload provider:

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
});

export default () => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
})

Local server#

By default Strapi accepts localServer configurations for locally uploaded files. These will be passed as the options for .

You can provide them by creating or editing the /config/plugins file. The following example sets the max-age header:

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

export default ({ env }) => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

Max file size#

:::note Strapi Cloud
On Strapi Cloud, upload size limits are enforced at the infrastructure level. They cannot be raised via the strapi::body middleware config. See Upload size limits for Strapi Cloud for per-plan values and the memory-based recommendation for image uploads.
:::

The Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 1 GB. This must be done in addition to provider options passed to the Upload package for sizeLimit.

You may also need to adjust any upstream proxies, load balancers, or firewalls to allow for larger file sizes. For instance, has a configuration setting called client_max_body_size that must be adjusted, since its default is only 1mb.

The middleware used by the Upload package is the body middleware. You can pass configuration to the middleware directly by setting it in the /config/middlewares file:

module.exports = [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // modify form body
      jsonLimit: "256mb", // modify JSON body
      textLimit: "256mb", // modify text body
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
      },
    },
  },
  // ...
];

export default [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // modify form body
      jsonLimit: "256mb", // modify JSON body
      textLimit: "256mb", // modify text body
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
      },
    },
  },
  // ...
];

In addition to the middleware configuration, you can pass the sizeLimit, which is an integer in bytes, in the /config/plugins file:

module.exports = {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
    }
  }
};

export default {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
    }
  }
};

Security#

The Upload plugin validates files based on their actual MIME type rather than the declared file extension.
Only files matching the defined security rules are uploaded.

The security configuration provides 2 options: allowedTypes or deniedTypes, which let you control which file types can or cannot be uploaded.

:::tip New projects
Apps scaffolded with create-strapi-app include a pre-configured security block in the generated config/plugins.* file. See the Security defaults generated by create-strapi-app details block below for the full lists.
:::

SVG uploads#

Since Strapi , image/svg+xml is part of the deniedTypes generated by create-strapi-app, so SVG uploads are refused even though they match the image/* wildcard in allowedTypes. An explicit deniedTypes entry always takes precedence over a wildcard in allowedTypes.

SVG files can embed browser-active content such as scripts and event handlers, which is why they are denied by default. This affects newly generated projects only: existing projects keep their current configuration unless you add the same entry yourself.

To accept SVG uploads, remove image/svg+xml from deniedTypes in your config/plugins.* file. Serve the resulting files from a domain that does not share cookies or local storage with your application, or with a Content-Disposition: attachment header, so an uploaded SVG cannot run scripts in the context of your site.

You can provide them by creating or editing the /config/plugins file. The following is an example of how to combine allowedTypes and deniedTypes:

module.exports = {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

export default {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

import type { Core } from '@strapi/strapi';

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

export default config;

Upload request timeout#

By default, the value of strapi.server.httpServer.requestTimeout is set to 330 seconds. This includes uploads.

To make it possible for users with slow internet connection to upload large files, it might be required to increase this timeout limit. The recommended way to do it is by setting the http.serverOptions.requestTimeout parameter in the config/servers file.

An alternate method is to set the requestTimeout value in the bootstrap function that runs before Strapi gets started. This is useful in cases where it needs to change programmatically, for example to temporarily disable and re-enable it:

module.exports = {

  //...

  bootstrap({ strapi }) {
    // Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

export default {

  //...

  bootstrap({ strapi }) {
    // Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

Responsive Images#

When the Responsive friendly upload admin panel setting is enabled, the plugin will generate the following responsive image sizes:

These sizes can be overridden in /config/plugins:

module.exports = ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

export default ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

Breakpoint changes will only apply to new images, existing images will not be resized or have new sizes generated.

Sharp configuration#

The sharp option configures the image processing library used for generating responsive image formats. Adjusting these settings can help reduce memory usage during image processing, which is particularly useful for memory-constrained environments.

The default values (cache: false, concurrency: 1) are optimized for low memory usage. For environments with more available memory, you can enable caching and increase concurrency to improve image processing performance:

module.exports = ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

export default ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

Usage#

Path to use the feature: Media Library

The Media Library displays all assets uploaded in the application, either via the Media Library itself or via the Content Manager when managing a media field.

Assets uploaded to the Media Library can be inserted into content-types using the Content Manager.

<ThemedImage
alt="Media Library overview, annotated"
sources={{
light: '/img/assets/media-library/media-library_overview2.png',
dark: '/img/assets/media-library/media-library_overview2_DARK.png',
}}
/>

From the Media Library, it is possible to:

• upload a new asset (see adding assets) or create a new folder (see organizing assets with folders) ,
• sort the assets and folders or set filters to find assets and folders more easily,
• toggle between the list view and the grid view to display assets, access settings to configure the view, and make a textual search to find a specific asset or folder,
• and view, navigate through, and manage folders .

Adding assets#

1. Click the Add new assets button in the upper right corner of the Media Library.
2. Choose whether you want to upload the new asset from your computer or from an URL:
   • from the computer, either drag & drop the asset directly or browse files on your system,
   • from an URL, type or copy and paste an URL(s) in the URL field, making sure multiple URLs are separated by carriage returns, then click Next.
3. (optional) Click the edit button to view asset metadata and define a File name, Alternative text and a Caption for the asset (see Managing individual assets).
4. (optional) Add more assets by clicking Add new assets and going back to step 2.
5. Click on Upload assets to the library.

<ThemedImage
alt="Add new assets window"
sources={{
light: '/img/assets/media-library/media-library_add-new-assets.png',
dark: '/img/assets/media-library/media-library_add-new-assets_DARK.png',
}}
/>

Automatically generating metadata with Strapi AI {#ai-powered-metadata-generation}#

When enabled, Strapi AI automatically generates alternative text and captions for images uploaded to the Media Library, helping you improve content accessibility and SEO. A modal window displays the AI-generated alternative text and caption, allowing you to review the metadata and modify it if needed:

<ThemedImage
alt="AI metadata review modal"
sources={{
light: '/img/assets/media-library/media-library_ai-metadata.png',
dark: '/img/assets/media-library/media-library_ai-metadata_DARK.png',
}}
/>

AI metadata generation only works with images, not files or videos. The feature is enabled by default, but can be disabled in the Media Library settings if needed.

The Media Library settings also allow generating metadata for existing images that lack alternative text or captions. This feature is currently in .

<ThemedImage
alt="AI metadata retroactive generation"
sources={{
light: '/img/assets/media-library/media-library_ai-metadata-retroactive.png',
dark: '/img/assets/media-library/media-library_ai-metadata-retroactive_DARK.png',
}}
/>

:::note Strapi AI credits

:::

Managing individual assets {#managing-assets}#

The Media Library allows managing assets, which includes modifying assets' file details and location, downloading and copying the link of the assets file, and deleting assets. Image files can also be cropped.

Editing assets#

Click on the edit button of an asset to open up the "Details" window, where all the available asset management options are available.

<ThemedImage
alt="Annotated asset details window screenshot"
sources={{
light: '/img/assets/media-library/media-library_asset-details.png',
dark: '/img/assets/media-library/media-library_asset-details_DARK.png',
}}
/>

• On the left, above the preview of the asset, control buttons allow performing various actions:
  • click on the delete button to delete the asset,
  • click on the download button to download the asset,
  • click on the copy link button to copy the asset's link to the clipboard,
  • optionally, click on the crop button to enter cropping mode for the image (see Cropping images).
  • optionally, click on the pin button to enter focal point mode for the image (see Adding a focal point).
• On the right, meta data for the asset is displayed at the top of the window and the fields below can be used to update the File name, Alternative text, Caption and Location (see Organizing assets with folders) for the asset .
• At the bottom, the Replace Media button can be used to replace the asset file but keep the existing content of the other editable fields, and the Finish button is used to confirm any updates to the fields.

Moving assets#

1. Click on the edit button for the asset to be moved.
2. In the window that pops up, click the Location field and choose a different folder from the drop-down list.
3. Click Save to confirm.

Cropping images#

1. Click on the edit button for the asset to be cropped.
2. In the window that pops up, click the crop button to enter cropping mode.
3. Crop the image using handles in the corners to resize the frame. The frame can also be moved by drag & drop.
4. Click the crop button to validate the new dimensions, and choose either to crop the original asset or to duplicate & crop the asset (i.e. to create a copy with the new dimensions while keeping the original asset untouched). Alternatively, click the stop cropping button to cancel and quit cropping mode.

5. Click Finish to save changes to the file.

Adding a focal point#

A focal point ensures the most important part of an image remains visible when the image is cropped or resized in different contexts.

To add a focal point to an image:

1. Click on the edit button.
2. In the window that pops up, click on the pin button to enter focal point mode.
3. Move the crosshair to the desired location and click to set the focal point.
4. Click the check button to validate the new focal point. Alternatively, click the cancel button to abandon changes and exit focal point mode.
5. Click the reset button to reset the focal point to the center of the image.
6. Click Finish to save changes to the file.

Deleting assets#

1. Click on the edit button for the asset to be deleted.
2. In the window that pops up, click the delete button in the control buttons bar above the asset's preview.
3. Click Confirm.

Organizing assets with folders#

Folders in the Media Library help you organize uploaded assets. Folders sit at the top of the Media Library view or are accessible from the Media field popup when using the Content Manager.

From the Media Library, it is possible to view the list of folders and browse a folder's content, create new folders, edit an existing folder, move assets to a folder, and delete a folder.

By default, the Media Library displays folders and assets created at the root level. Clicking a folder navigates to this folder, and displays the following elements:

• the folder title and breadcrumbs to navigate to a parent folder
• the subfolders the current folder contains
• all assets from this folder

<ThemedImage
alt="Media library one folder deep, with back button and updated folder title"
sources={{
light: '/img/assets/media-library/media-library_folder-content.png',
dark: '/img/assets/media-library/media-library_folder-content_DARK.png',
}}
/>

From this dedicated folder view, folders and assets can be managed, filtered, sorted and searched just like from the main Media Library.

To navigate back to the parent folder, one level up, use the Back button at the top of the interface.

Adding folders#

1. Click on Add new folder in the upper right of the Media Library interface.
2. In the window that pops up, type a name for the new folder in the Name field.
3. (optional) In the Location drop-down list, choose a location for the new folder. The default location is the active folder.
4. Click Create.

Moving assets to a folder#

Assets and folders can be moved to another folder from the root view of the Media Library or from any view for a dedicated folder.

1. Select assets and folder to be moved, by clicking the checkbox on the left of the folder name or clicking the asset itself.
2. Click the Move button at the top of the interface.
3. In the Move elements to pop-up window, select the new folder from the Location drop-down list.
4. Click Move.

<ThemedImage
alt="'Move elements to' popup"
sources={{
light: '/img/assets/media-library/media-library_move-assets.png',
dark: '/img/assets/media-library/media-library_move-assets_DARK.png',
}}
/>

Editing folders#

Once created, a folder can be renamed, moved or deleted.

1. In the Folders part of the Media library, hover the folder to be edited and click its edit button .
2. In the window that pops up, update the name and location with the Name field and Location drop-down list, respectively.
3. Click Save.

Deleting folders#

Deleting a folder can be done either from the list of folders of the Media Library, or when editing a single folder.

1. Click the checkbox on the left of the folder name. Multiple folders can be selected.
2. Click the Delete button above the Folders list.
3. In the Confirmation dialog, click Confirm.

Usage with the REST API#

The Media Library feature has some endpoints that can accessed through Strapi's REST API:

Use public assets in your code {#public-assets}#

Public assets are static files (e.g., images, video, CSS files, etc.) that you want to make accessible to the outside world.

Because an API may need to serve static assets, every new Strapi project includes by default a folder named /public. Any file located in this directory is accessible if the request's path doesn't match any other defined route and if it matches a public file name (e.g. an image named company-logo.png in /public/ is accessible through /company-logo.png URL).

The dotfiles are not exposed. It means that every file name that starts with ., such as .htaccess or .gitignore, are not served.