Media entity provides a 'base' entity for media. This is a very basic entity
which can reference to all kinds of media-objects (local files, YouTube
videos, Tweets, Instagram photos, ...). Media entity provides a relation between
Drupal and the media resource. You can reference to/use this entity within any
other Drupal entity.

This module attempts to provide the base storage component for the Drupal 8
media ecosystem.

Media Entity will be in core

This module is being moved to Drupal 8 core! Starting with Drupal 8.4 there is a Media module in Drupal core, which includes the base API from Media Entity, as well as most of the functionality provided by Media Entity Image and Media Entity Document. The base API will be added to 8.4.x so that contrib maintainers and module developers can start porting their modules to the new API. In future releases (8.5.x, etc), more features and UX improvements will be added and the module will then be considered ready for general usage. You can follow the full roadmap and related issues here.

What version of Media Entity should I use for a new project right now?

Short answer: 8.x-1.x. It is compatible with Drupal core 8.4.x and there will be an upgrade path when everything is ready to upgrade.

Long answer: keep reading.

Upgrade path

If you want to help testing the upgrade path, you can follow these


  1. Backup your code and your database
  2. Test that you can successfully roll-back from the backup!
  3. Upgrade the codebase with:
    • Core: >= 8.4.x
    • Media Entity: 8.x-2.x
    • All media entity providers: 8.x-2.x (or use patches from #2860796: Plan for contributed modules with Media Entity API in core). Note that the modules Media Entity Image and Media Entity Document, if present, don't need to be updated. Their configs will be updated by the main Media Entity updates.
    • All modules that depend on or interact with Media Entity: 8.x-2.x
    • The new contrib module Media Entity Actions: 8.x-1.x
    • If your site uses media entities with the "Generic" provider, make sure you download to your codebase the Media Entity Generic module as well.
  4. Clear your caches
  5. (Optional) Check that all requirements for the upgrade are met with drush mecu.
    IMPORTANT: Please note that if you are running DB updates with Drush 9 (between 9.0.0-alpha1 and 9.0.0-beta7), you are strongly encouraged to use this command prior to running the updates. Drush 9 will not run the requirements validation and will try to run the updates even if your site has some of the requisites misconfigured. Executing the updates in that scenario will likely break your site. This was fixed in Drush 9.0.0-beta8. Drush 8 users don't need to worry about this.
  6. Run the DB Updates, either by visiting /update.php, or using drush updb
  7. Double-check that the Media Entity module is uninstalled, and remove it from the codebase. Remove also Media Entity Image / Document, if present.

Known issues concerning the upgrade path:
- If your existing site used tokens provided by Media Entity ([media:*]), you are recommended to install the Token module, which will provide token replacements for almost all of them. Some differences may still exist, and those are being treated specifically in #2877378: Add token replacements for Media.
- Entity Browser has a 2.x branch that has new features for media in core, for example the widget that was formerly present in the "Media Entity Image" module. However, if you intend to upgrade Entity Browser to the 2.x branch, you should do that only after performing the main Media Entity upgrades. There is currently a bug preventing the Media Entity upgrade if the Entity Browser 2.x is present in the codebase.

Compatibility restrictions

If your site currently uses Media Entity, in order to move to the Drupal core Media solution in the future, you will need to upgrade to Media Entity 8.x-2.x, following the above mentioned upgrade path.

Note that in order to start using the Drupal core's Media module, all provider modules defining media source plugins will need to be upgraded as well. There is an issue that keeps track of the upgrade status of the most common contributed modules.

If you need to upgrade Drupal core to 8.4.x but you can't yet upgrade Media Entity 8.x-2.x due to some contrib modules not having 2.x branches, you still can use Media Entity 8.x-1.x with Drupal 8.4.x, as long as the core Media module is not enabled. If you can, consider helping with the upgrade of contrib modules. Media Entity 8.x-1.x will become unsupported at some point in the future (as more sites move over to the core Media module).

There's also more information about this transition phase in the FAQ handbook page.


Our current development focus can be seen in the roadmap issue.

Development is generally done via GitHub pull requests.
Every pull request should be linked to an issue in issue queue and vice-versa.

If you prefer usual patch-based workflow feel free to submit a patch. We started
using GitHub mostly for easier review process. However, there are no strong opinions
about that. Any contribution in any shape or form will be treated equally.

Media provider modules

There are already several media provider modules that extend functionality of
Media entity:

Other modules that integrate with media entity

Media entity 8.x-1.0-beta2 to 8.x-1.0 update instructions

We started depending on the Entity API module. In order for update to go smoothly please make sure that the Entity API >= 8.x-1.0-alpha3 is installed before updating Media entity.


Get in touch


Initial development of Media entity and media provider plugins was partly sponsored by, part of Outbox AXS.

Supporting organizations: 
Initial development and maintenance.
Initial development.
Development and maintenance.
Development and maintenance.
Development and maintenance.

Project information