--- url: /panel/media-library.md --- # Media library The media library at `/evolve/media` holds every uploaded file: images, documents, video and audio. Images are rendered into the variants the theme asks for; everything else is served as uploaded. Blocks and records reference media by ID, so a file replaced in the library changes everywhere it is used. ![The file manager: search, type filter, folders, upload, and the cards with usage count and row menu](/screenshots/panel-media-library.png) ## Who can open it `evolve.roles.media` lists the roles, default `developer`, `admin` and `content_manager`; the permission is `media.manage`. See [Roles](/getting-started/roles#restricting-panel-areas). ## Uploads | Setting | Default | Where | |---|---|---| | Maximum file size | 10000 KB | `evolve.media-manager.max-file-size` in `config/evolve.php` | | Allowed extensions | jpg, jpeg, png, gif, webp, avif, bmp, ico, pdf, doc, docx, xls, xlsx, ppt, pptx, csv, txt, mp4, webm, mov, mp3, wav, ogg, zip | `evolve.media-manager.allowed-extensions` | SVG, HTML, XML and JavaScript are excluded on purpose: the browser executes them when served from the media URL, which turns an upload into stored cross-site scripting. Add an extension only when that risk is understood. Neither setting has a `.env` key; publish the config to change them. ## Working in the library * **Folders**: create, rename, delete, move files and folders between them. The path shows above the grid. * **Filters**: All, Images, Documents as a segmented control; grid or list; "Not attached" shows files no record references. * **Tags** on files, shared with the rest of the panel. * **File drawer** (since 2.13): preview with the focal point on top, name, description, alt text and tags below, Replace and Delete in the footer. The focal point decides what survives when the theme crops an image. * **Used by**: the drawer lists every record and field that references the file, and the card shows the count. A file still in use cannot disappear silently. * **Download selected** zips the selection. * **Approval and rights** (badges, filters, a governance block in the drawer, bulk review) come with the [Media Governance](/modules/media-governance) module, off by default. ## File URLs Documents, video, audio and every other file that is not rendered as an image are served under a readable URL: the hash identifies the file, the name follows as a slug with the extension. ``` /media/dGVpG23oQz/pflegeanleitung-grosse-2026.pdf ``` The copy link button on the card, in the list and in the search palette copies this URL, and the downloads block links it. Only the hash decides which file is served, so a renamed file keeps working under its old link, and the slug in an old link may be anything. Links without a slug (`/media/dGVpG23oQz` and `/media/dGVpG23oQz/`, the shape before 2.19) keep working unchanged, as do `/media/{hash}/download` (always a download) and `/media/{hash}/preview` (the first page of a PDF as an image). The browser shows the file under its media name, with umlauts, in both cases. In a template, `$media->path()` returns this URL for files and the rendered variant for images; `$media->filePath()` returns the readable URL of the original file for every type, images included. ## Image metadata and recognition On upload, Evolve reads width, height and EXIF data. With `IMAGE_RECOGNITION=true` and a Google service account in `GOOGLE_APPLICATION_CREDENTIALS`, Cloud Vision adds labels (objects, logos, visible text) as suggested tags so that images are searchable without manual tagging. `php artisan evolve:update-image-metadata` fills in metadata for files that were uploaded before, or when recognition was turned on later. ## Image rendering The theme requests image variants (sizes, crops, WebP and AVIF derivatives) through ``. Variants render on first request, or in a queue when `QUEUE_CONNECTION` is not `sync`. `IMAGE_DRIVER` chooses `gd` (default) or `imagick`; `IMAGE_ALLOW_IDS` lets a template request an image by ID. The full pipeline, including `evolve:images:warm` and `evolve:clear-images`, is on [Image Rendering](/frontend/image-rendering). ## Maintenance commands | Command | Does | |---|---| | `evolve:index-media-usages` | Rebuilds the "used by" index from blueprint fields and inline links in block content. Run after importing content or when counts look wrong. | | `evolve:prune-media-attachments` | Removes attachments that point to deleted records or to model classes that no longer exist. | | `evolve:update-image-metadata` | Reads and saves missing image metadata, with recognition when enabled. | | `evolve:images:warm [--missing]` | Queues the variants the theme requests, all or only the missing ones. | | `evolve:clear-images` | Deletes every rendered variant; they render again on request. | Media files live in `storage/app` and are shared between releases since 2.12 (`shared/storage/app`), so a deploy keeps them and `evolve:env:setup` and the Envoy media tasks move them between environments. See [Deployment](/getting-started/deployment#shared-storage). ## Verifying Upload an image, set a focal point, place it on a page and check the crop in the frontend. Open the file drawer: "Used by" names the page. `php artisan evolve:index-media-usages` reports the number of usages it indexed.