Media Library Importer
A module to import media files from public directory into the Drupal Media Library with queue-based batch processing.
media_library_importer
Install
composer require 'drupal/media_library_importer:^2.1'
Overview
Media Library Importer provides a streamlined solution for bulk importing existing media files from your server's file system into Drupal's Media Library. It scans specified directories for media files and creates corresponding Media entities for each file, maintaining the proper relationship between files and media types.
The module uses a queue-based approach with batch processing to handle large imports efficiently without timing out. Files are matched to media types based on their extensions, and the module intelligently prevents duplicate imports by checking if a media entity with the same source file already exists.
Import operations can be triggered through the admin UI, via Drush commands, or programmatically through cron jobs, providing flexibility for various workflows.
Features
- Bulk import media files from any directory within the public file system into the Media Library
- Queue-based batch processing using Queue UI for handling large imports without timeouts
- Automatic media type detection based on file extensions configured in each media type
- Duplicate prevention - media entities are not recreated if they already exist with the same source file
- Option to copy imported files to the media type's designated storage location or keep them in place
- Configurable exclusion of the image styles folder to prevent importing derivative images
- Support for multiple media types including Image, Document, Audio, Video, and any custom media types
- Drush command integration for command-line imports (drush media-library:import or drush mli)
- Programmable cron-based imports for automated scheduled imports
- Hook for adding extra field values to media entities during import
Use Cases
Migrating from unmanaged files to Media Library
When upgrading a site that previously used unmanaged files or File entities to the Media Library system, Media Library Importer can bulk import all existing files. Configure the import folder to point to your files directory, select appropriate media types, and run the import to create Media entities for all existing files.
Bulk uploading media via FTP or file transfer
For sites that receive large batches of media files via FTP or file transfer, Media Library Importer provides a workflow to add these files to the Media Library. Upload files to a designated import folder, then use the admin UI or Drush command to import them all at once.
Automated scheduled imports via cron
Set up automated imports by implementing hook_cron() in a custom module. Call $media_library_importer_service->generateImportQueue() followed by processImportQueue() to automatically import new files added to the import folder on each cron run.
Importing image libraries with EXIF metadata
When importing photography or image collections, enable the Media Image EXIF Importer submodule to automatically extract and store camera metadata including model, ISO, aperture, exposure time, and focal length from each imported image.
Integrating with content migration
Use the hook_alter_media_library_importer_media_extra_fields hook to populate additional media fields during import. This is useful when migrating content where media metadata should be populated from external sources or filenames.
Tips
- Run imports via Drush (drush mli) for large batches as it handles long-running processes better than the web interface.
- Use the 'Exclude styles folder' option to prevent importing image derivatives as separate media entities.
- The module checks for existing media by filename and bundle, so files can be added to the import folder and the import run multiple times without creating duplicates.
- For incremental imports, place new files in the import folder and run the import again - only new files will be processed.
- Enable the Media Image EXIF Importer submodule before importing images to capture camera metadata during the initial import.
- Configure the media type field mappings correctly - the module needs to know which field stores the media file for each media type.
Technical Details
Admin Pages 2
/admin/config/media/media-library-importer
Configure settings for the Media Library Importer including import source folder, media types to import, and file handling options.
/admin/config/media/media-library-importer/import
Execute the media import operation. Displays a tree of folders within the configured import directory with counts of importable media files. Select folders to include in the import and run the batch process.
Permissions 2
Hooks 1
hook_alter_media_library_importer_media_extra_fields
Allows modules to add additional field values to media entities during import. Called during queue generation for each file being imported.
Drush Commands 1
drush media-library:import
Import media entities according to the configured Media Library Importer settings. Scans the configured import folder and creates media entities for all matching files that don't already exist in the Media Library.
Troubleshooting 5
The 'Import files to location set in media' option copies files to the media type's configured directory. If you want to keep files in their original location without copying, uncheck this option in the configuration form.
Ensure the 'Exclude media image styles folder' checkbox is checked in the configuration. This prevents the /styles directory (containing image derivatives) from being scanned during import.
The module uses Queue UI for batch processing which handles large imports. If still experiencing issues, increase PHP execution time limits or run imports via Drush command which can handle longer processing times.
Check that the file extension is allowed in the configured media type's source field settings. The module matches files to media types based on their extensions. Also verify the import folder path is correct and accessible.
This is expected behavior. The module uses the filename as the media entity name. Use the hook_alter_media_library_importer_media_extra_fields hook to customize the media name or other fields during import.