Working with media

In lay parlance, “media” is a nonspecific term that can refer to images, documents, and videos you upload as well as external content referenced on your site. In the Drupal Kit, “media” has a more specific meaning. This page clarifies unfamiliar terminology related to Drupal media and offers practical tips for integrating media.


What “files” and “media” mean in Drupal

In Drupal, files and media have distinct technical meanings:

  • File: an actual digital file, such as a .pdf document or a .jpg image, stored in the site’s filesystem. Drupal keeps track of these files through a numbering system (“File 1”, “File 2”), so that the site can retrieve the actual file when referenced in page content. Drupal files store only very basic information: the file size, file type, and upload date.

  • Media: a system for referencing and displaying files. Content editors create media entities by associating a file reference with other metadata (alt text for an image, or a thumbnail for a video, for example). Drupal keeps track of these through a separate numbering system (“Media item 1”, “Media item 2”). Content editors can then display these media items in content. One media item can display in multiple places, and can have different displays in those different contexts.

Practically speaking, content editors interact directly with Drupal media. They only indirectly reference files through the media items they create. Content editors do upload files, but do so by creating a media item that references the file.

The Media Library

All media added to the site displays in the Media Library and becomes available to reference anywhere in the site. Anything in the Media Library can be inserted, by any content editor, into a rich text area, or into a display element that has a media component.

Access the Media Library at Content > Media (/admin/content/media)

Screenshot of the Drupal Media Library

The important takeaway: all media is shared across content editing, and any given media item can display in multiple places. Media added from within a specific page still ends up in the Media Library.

Put another way, there is no way to limit a media item’s usage to only one location. Because of this, deleting media includes risks, as discussed below.

Creating media

There are two ways to add media for general use on the site: #. Upload new media items to the Media Library directly from Content > Media > Add media (/media/add) #. Add media during page creation, from either a rich text toolbar or from a component that has a media upload option.

Whichever the method, the new media item will show in the Media Library, eligible for reuse anywhere on the site.

Deleting media

Because Drupal media are shared assets, exercise caution when considering deletion. You may have added it in one place, but another content editor may be referencing it elsewhere. Instead of deleting the media item, a safer approach is to remove the reference where the media item displays (e.g., by editing page content).

Because of the likelihood of someone unintentionally deleting shared media (/admin/content/media), the system currently does not allow you to delete Drupal files (/admin/content/file), period. The Drupal Kit team is developing a solution that will allow permanent file deletion. In the meantime, if you need to delete a file, email .

Disambiguation: “media” vs. “embedded content”

In the context of a Drupal Kit site, media is distinct from embedded content. Embeds are external media, such as Qualtrics forms or other Other embeds that require <script> or <iframe> tags. These embeds are not part of the Drupal media system and not stored in the Media Library.

When to use an external file sharing service instead of uploading files?

For images displayed inline in your website pages, it’s best to upload the images directly to the site.

For everything else (documents, high-resolution images for download), link to files on a third-party cloud file sharing platform such as Box or SharePoint. See the Drupal Kit knowledge base article for a complete explanation.