---
title: Configuring media libraries
related:
  - https://docs.kentico.com/13/managing-website-content/working-with-files/media-library-files.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Using the Media libraries application, users can store various files, for example, photos, pictures, sound files, videos, package files, presentations or document files. This means that media libraries are able to store non-media types of files as well.  You can set the site up to allow visitors to view and add content to media libraries.

This page covers some of the more general Media library settings:

> **Note:** **Storage of media files in Xperience projects**
>
> By default, content of media libraries is synchronized via [web farms](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms.md) and duplicated in the project directories of both the Xperience and live site applications. To store media files in a single location, use the approach described in [Configuring custom storage for media libraries](#configuring-custom-storage-for-media-libraries).

See the subpages for additional configuration scenarios.

## Adjusting general media library settings

1. Navigate to  **Settings → Content → Media**.
2. Adjust the [relevant settings](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites/settings-content/settings-media.md).
3. **Save**  the changes.

## Configuring the media file URL format for content

The system can serve files from media libraries via two types of URLs:

- **Permanent** – an application relative path to the file (starting with '_\~/_'). For example: _\~/getmedia/0140bccc-9d47-41ea-94a9-ca5d35b2964c/sample\_image.jpg_. This format ensures that the image remains accessible if the file is renamed, reuploaded, or moved to a different media library or file system directory.
- **Direct file path** – a direct path to the media file on the file system. For example: _\~/MediaLibraryFolder/sample\_image.jpg_. These URLs change whenever the file is renamed, moved to a different media library or file system directory, or if the file is updated with a different name or extension.

> **Note:** **Note**: Files accessed through a direct path are not handled by the Xperience system – no permission or security restrictions are enforced and image resizing is not applied. Additionally, direct file links may become broken in certain deployment scenarios if your instances each use a different location or container for media files.

When editors add a media library file to content in the Xperience administration interface, the system uses the permanent URL format by default. If you wish to use direct file path URLs, you can configure individual media libraries:

1. Open the **Media libraries** application.
2. Edit a specific library.
3. Select the **General** tab.
4. Enable the **Use direct path for files in content** option.
5. Click **Save**.

The configured URL format applies in the following scenarios:

- Adding media files using the [Rich text widget](https://docs.kentico.com/13/managing-website-content/editing-rich-text-content/using-the-rich-text-widget.md) in page builder content
- Adding media files using the [editor](https://docs.kentico.com/13/managing-website-content/editing-rich-text-content/editing-content-in-rich-text-fields.md) for page fields based on the the **Rich text editor** form control
- [Selecting media files](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-media-libraries/allowing-users-to-insert-media-links-in-page-fields.md) in page fields based on the **Media selection** form control

## Configuring maximum file upload size in media libraries

The default maximum size for files uploaded into media libraries is approximately 28.6MB (limited by the IIS [Request Limits](https://learn.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/requestlimits/) configuration). To enable uploads of larger files:

1. Edit your project's  **web.config**  file.
2. If necessary, modify the value of the **** element's  **maxRequestLength**  attribute. Enter the value in  **kiloBytes**.

   > **Note:** **Important**: Modify the **** element directly under the web.config's main **** section, NOT within a specific **** element.

   ```html

   <httpRuntime maxRequestLength="2000000" ... />

   ```
3. Add the following **** element into the web.config's main **** section. Enter the value of the **** element's  **maxAllowedContentLength**  attribute in  **Bytes**.

   ```html

   ...
   <system.webServer>

     <security>
       <requestFiltering>
         <requestLimits maxAllowedContentLength="2147483648"/>
       </requestFiltering>
     </security>

     <modules>
         <remove name="XHtmlModule" />
         <remove name="CMSApplicationModule" />
         ...

   ```
4. Save the  **web.config**  file.

Users can now upload files in the size that you specified in the  **maxRequestLength**  and  **maxAllowedContentLength**  attributes into Media libraries.

## Format of media library files on the disk

When the thumbnail image or the image itself is larger than the required thumbnail image size, the system creates a copy in the required size. Both thumbnails and resized copies are stored in a **hidden folder** in the root of the media library folder. You can set the name of the folder in **Settings → Content → Media → Media file hidden folder**.

- **File**: .
- **Resized file**: /__\_.
- **Thumbnail**: /\_.
- **Resized thumbnail**: /__\_.

**Note**: Thumbnails are not generated automatically for **WebP** and **SVG** images.

### Example

If you upload the following files:

- **Uploaded file**: _MyImage.jpg_
- **Uploaded thumbnail**: _MyPhoto.bmp_

with the following settings defined in **Settings -> Content -> Media**:

- **Media file hidden folder**: \_\__thumbnails_
- **Media file thumbnail suffix**: \__thumbnail_

the system stores the uploaded files in the media library folder with the following names:

- **File**: _MyImage.jpg_
- **Resized file**: \_\__thumbnails/MyImage\_jpg\_100\_200.jpg_
- **Thumbnail**: \_\__thumbnails/MyImage\_jpg\_thumbnail.bmp_
- **Resized thumbnail**: \_\__thumbnails/MyImage\_jpg\_thumbnail\_20\_30.bmp_

## Configuring custom storage for media libraries

The default location of all libraries of a particular site is **\~//media**. To customize the location:

1. Navigate to  **Settings → Content → Media → Media libraries folder**.
2. Enter the folder location you want the system to store the files in. The location needs to be in one of the following formats:
   1. **physical path** – for example, _c:\Libraries._
   2. **root-relative path** – for example, _\~/Libraries._
   3. **UNC path** – for example, _\\\\\Libraries._
      - **Note**that if you want to use a UNC path while hosting your media library on a different server, you need to use the _CMSAllowCheckIOPermissions_ [web.config](https://docs.kentico.com/13/configuring-xperience/reference-web-config-application-keys.md) key set to false.
3. (Optional) Enable the **Use site-specific subfolders for custom media libraries folder** option. The system then stores media library files in a sub-folder named as the site code name under the custom files folder. That is, _/_.
4. **Save** the changes.

> **Note:** **Notes**:
>
> - When you change the location of the media library folders, the system does NOT automatically move existing media files and sub-folders to the new location. To ensure that your media content is accessible and works correctly, you need to manually move the files from the old location to the new one in the file system.
> - The [media file API](https://docs.kentico.com/13/developing-websites/retrieving-content/displaying-content-from-media-libraries.md) always generates permanent URLs for media files stored in custom media library folders located outside your project.

> **Info:** If you are running the system on a **web farm** and have **the same UNC root defined** on all servers, it is necessary to add the following key into your _web.config_ file. The files stored in the libraries are then not transferred when synchronizing the web farm content:
>
> ```html
>
> <add key="CMSWebFarmSynchronizeMediaFiles" value="false"/>
>
> ```

## Media library limitations when storing files in an external storage

If your project is configured to store files in an external storage, for example [Azure Blob Storage](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers/configuring-azure-storage.md) or [Amazon S3](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers/configuring-amazon-s3.md), make sure that you structure the media files into a hierarchy of folders. Storing a large number of media files in a single folder can significantly affect the performance of your project when editing the files in the Media library application.

We recommend storing at most 100 files in a single media library folder. Once you reach the limit, make sure you create a structure that allows you to divide the files into multiple folders. The number of files in one folder directly affects the performance of the Media library user interface.

Additionally, the system's automatic clearing of files from the server-side cache does not work for files stored in an external storage. If you modify a media file, the website may still display the old version until the cache expires (unless you manually clear the application's cache). See also: [Caching files and resources](https://docs.kentico.com/13/configuring-xperience/configuring-caching/caching-files-and-resources.md)