---
url: /reference/configuration.md
description: >-
  Every key in config/filament-media-library.php with its type, default and what
  it does, grouped like the file.
---

# Configuration

Publish the file with `php artisan vendor:publish --tag=filament-media-library-config`, or run `php artisan media-library:install`. The config lives at `config/filament-media-library.php`.

Inside a Filament panel, the fluent options on the [plugin](/reference/plugin) override `features`, `browser`, `upload.accepted_mime_types`, `upload.max_file_size`, `upload.duplicates` and tenancy. Outside panels, this file is the only place to set them.

## Models and tables

| Key | Type | Default | What it does |
|---|---|---|---|
| `models.item` | class-string | `MediaItem::class` | The model for library files. Swap it to extend the built-in model. |
| `models.folder` | class-string | `MediaFolder::class` | The folder model. |
| `models.tag` | class-string | `MediaTag::class` | The tag model. |
| `models.attachment` | class-string | `MediaAttachment::class` | The pivot model that records where a file is used. |
| `table_prefix` | string | `'media_library_'` | Prefix for the library tables. |
| `user_model` | class-string or `null` | `null` | The model for uploaders and owners. `null` uses your auth provider's model. |

## Key types

Set these before you run the migration.

| Key | Type | Default | What it does |
|---|---|---|---|
| `key_types.user` | `int`, `uuid`, `ulid` or `string` | `'int'` | Column type for `uploaded_by` and `created_by`. |
| `key_types.tenant` | same | `'int'` | Column type for the tenant foreign key. See [Multi-tenancy](/guide/tenancy). |
| `key_types.attachable` | same | `'int'` | Column type for the model that uses a file. |

## Disk

| Key | Type | Default | What it does |
|---|---|---|---|
| `disk` | string | `env('MEDIA_LIBRARY_DISK', env('MEDIA_DISK', 'public'))` | The disk that holds originals. |
| `conversions_disk` | string or `null` | `null` | A separate disk for thumbnails and conversions. `null` keeps them with the original. |
| `temporary_url_minutes` | int | `30` | Lifetime of temporary URLs (S3) and signed streaming links (local) for files on a private disk. |
| `route_prefix` | string | `'media-library'` | URL prefix for the upload, download and serve routes. |

See [Storage & S3](/guide/storage).

## Upload

| Key | Type | Default | What it does |
|---|---|---|---|
| `upload.max_file_size` | int (kilobytes) | `512 * 1024` | Largest file, 512 MB by default. `0` removes the limit. |
| `upload.chunk_size` | int (bytes) | `5 * 1024 * 1024` | Size of each chunk the browser sends. The server never accepts a value under 256 KB. |
| `upload.max_parallel_uploads` | int | `3` | Files the browser uploads at the same time. |
| `upload.accepted_mime_types` | array | images, video, audio, PDF, ZIP, text, CSV, Office documents | MIME patterns the library accepts. `image/*` style wildcards work. |
| `upload.blocked_extensions` | array | scripts, executables, `html`, `xml`, `js` and similar | Extensions that are always refused, whatever the MIME type says. |
| `upload.sanitize_svg` | bool | `true` | Strip scripts and unsafe markup from SVG uploads. |
| `upload.preserve_file_names` | bool | `false` | Keep the original file name on disk instead of a generated one. |
| `upload.duplicates` | `DuplicateStrategy` | `DuplicateStrategy::Ask` | What happens when a file matches an existing one by hash. `Ask`, `Allow` or `UseExisting`. |
| `upload.url_import` | bool | `true` | Allow importing files from a URL. The `url_import` feature overrides it. |
| `upload.chunk_directory` | string | `'media-library-chunks'` | Folder under `storage/app` for unfinished chunks. |

See [Uploading](/guide/uploading) and [Security](/guide/security).

## Conversions

`conversions` is an array keyed by conversion name. The defaults:

```php
'conversions' => [
    'thumb' => ['width' => 480, 'height' => 480, 'fit' => 'crop', 'format' => 'webp', 'queued' => false],
    'preview' => ['width' => 1600, 'height' => 1600, 'fit' => 'contain', 'format' => 'webp', 'queued' => true, 'responsive' => true, 'optimize' => true],
],
```

| Option | Type | What it does |
|---|---|---|
| `width`, `height` | int | Target size in pixels. |
| `fit` | string | `crop`, `contain` and the other Spatie fit modes. Cropped conversions follow the focal point. |
| `format` | string | Output format, for example `webp`. |
| `queued` | bool | Generate on the queue. `thumb` is synchronous so new uploads appear at once. |
| `responsive` | bool | Generate responsive image variants. |
| `optimize` | bool | Run Spatie's image optimizers. Slow, so queue it. |

Add your own names to use them with `<x-media-library-image>` and the table columns.

## Versions

| Key | Type | Default | What it does |
|---|---|---|---|
| `versions.enabled` | bool | `true` | Keep the previous file when you replace or save an edit as a new version. |
| `versions.keep` | int | `10` | Versions kept per file. Older ones are pruned. |

## Tenancy

| Key | Type | Default | What it does |
|---|---|---|---|
| `tenancy.enabled` | bool | `false` | Scope the library to a tenant outside panels. Panels with tenancy do this on their own. |
| `tenancy.resolver` | class-string | `FilamentTenantResolver::class` | The class that returns the current tenant. `StanclTenantResolver` ships with the package. |
| `tenancy.strict` | bool | `true` | Show nothing when no tenant resolves. |

See [Multi-tenancy](/guide/tenancy).

## Private media

| Key | Type | Default | What it does |
|---|---|---|---|
| `private_media` | bool | `true` | Let uploaders mark files and folders private. Private records are visible to their owner and to users who pass `viewPrivate`. |

See [Private files](/guide/private-files) and [Authorization](/reference/authorization).

## Quota

| Key | Type | Default | What it does |
|---|---|---|---|
| `quota` | int, `null` or invokable class-string | `null` | Maximum bytes per tenant, or for the whole app without tenancy. An invokable class receives the current tenant and returns bytes or `null`. |

## Trash

| Key | Type | Default | What it does |
|---|---|---|---|
| `trash.enabled` | bool | `true` | Move deleted files to the trash. When off, deleting removes the file for good. |
| `trash.prune_after_days` | int | `30` | Age at which `media-library:prune` removes trashed files. |

## Alt text

| Key | Type | Default | What it does |
|---|---|---|---|
| `alt_text.generator` | class-string | `NullAltTextGenerator::class` | Class that writes alt text. Use `AnthropicAltTextGenerator::class` for Claude, or your own `AltTextGenerator`. |
| `alt_text.auto_generate` | bool | `false` | Describe every new image on the queue. |
| `alt_text.anthropic.api_key` | string | `env('ANTHROPIC_API_KEY')` | API key for `AnthropicAltTextGenerator`. |
| `alt_text.anthropic.model` | string | `env('MEDIA_LIBRARY_ALT_TEXT_MODEL', 'claude-opus-5-5')` | Model used for descriptions. |

See [AI alt text](/guide/alt-text).

## Browser

| Key | Type | Default | What it does |
|---|---|---|---|
| `browser.per_page` | int | `48` | Items loaded per page. |
| `browser.default_layout` | `'grid'` or `'list'` | `'grid'` | Starting layout. |
| `browser.default_sort` | string | `'newest'` | Starting sort: `newest`, `oldest`, `name_asc`, `name_desc`, `largest`, `smallest`. |
| `browser.tile_size` | int | `180` | Grid tile size in pixels. The plugin clamps it between 120 and 280. |

## Features

Each key switches one part of the library on or off. `null` keeps the default, which is on. The four keys that default to `null` also honour their older config key (`trash.enabled`, `private_media`, `versions.enabled`, `upload.url_import`).

| Key | Default |
|---|---|
| `features.folders`, `tags`, `favorites` | `true` |
| `features.trash` | `null` |
| `features.private_media` | `null` |
| `features.versions` | `null` |
| `features.image_editor`, `focal_point` | `true` |
| `features.url_import` | `null` |
| `features.folder_upload`, `alt_text`, `duplicate`, `download`, `exif`, `usage`, `smart_views`, `keyboard_shortcuts` | `true` |

The [plugin](/reference/plugin#features) lists what each flag turns off.

## Standalone

| Key | Type | Default | What it does |
|---|---|---|---|
| `standalone.enabled` | bool | `false` | Allow the picker and library on your own Livewire and Blade pages. When off, the standalone routes return 404. |
| `standalone.middleware` | array | `['web', 'auth']` | Middleware for the standalone upload and download routes. |

Read [Outside Filament panels](/guide/outside-panels) before you turn this on. The default policy lets every signed-in user manage shared media, so register your own policy first on a site with customer accounts.