---
title: "Usage"
manual: "Filefix"
version: "main"
permalink: "https://docs.typo3.org/permalink/anubit/filefix:usage@main"
source: "Usage/Index.rst"
rendered: "2026-10-16T12:43:55+00:00"
---

# Usage {#usage}

-   [MIME Fix inside the file list](https://docs.typo3.org/permalink/anubit/filefix:mime-fix-inside-the-file-list@main)
-   [File Cleanup](https://docs.typo3.org/permalink/anubit/filefix:file-cleanup@main)
-   [Duplicate report](https://docs.typo3.org/permalink/anubit/filefix:duplicate-report@main)
-   [Oversized images](https://docs.typo3.org/permalink/anubit/filefix:oversized-images@main)
-   [Dashboard widgets](https://docs.typo3.org/permalink/anubit/filefix:dashboard-widgets@main)

## MIME Fix inside the file list {#usage-mimefix}

No separate module to learn. A **Scan MIME** button is injected into
the toolbar of the TYPO3 **File > Filelist** module for the folder you
are viewing.

It reports every file in that folder where:

-   the **actual file content** does not match what the **extension** claims
    it is (`finfo` vs. extension), or
-   the **database** `mime_type` is out of sync with what it should be.

Supported types: `jpg`, `jpeg`, `png`, `gif`, `webp`, `bmp`,
`tiff`/`tif`, plus the text-based `css`, `js`, `yaml`/`yml` and
`dotx`.

| Situation | What happens |
| --- | --- |
| Image content does not match extension (for example a PNG saved as `.jpg`) | Converted in place via ImageMagick / GraphicsMagick, written to a temp file first so a failed conversion never corrupts the original. |
| Photoshop file (`.psd` content, wrong extension) | Converted via the PHP `Imagick` extension if available; falls back to ImageMagick `convert`, reading only the merged/composite layer. |
| `css` / `js` / `yaml` / `yml` / `dotx` | `finfo` cannot detect these correctly, so only the `sys_file.mime_type` record is corrected. |

Select the issues, click **Fix selected**. The FAL index is re-read
afterwards so TYPO3 immediately reflects the corrected type.

## File Cleanup {#usage-cleanup}

**File > File Cleanup**. For when you trust the result and want the
files gone.

-   Lists files with **zero active** `sys_file_reference` and **zero soft
    references** (`sys_refindex`), that is, unreferenced by any page,
    content element or FlexForm.
-   Filter by **Present on disk** / **Physically missing** /
    **All**, by extension and by folder depth (level 1 to 3, or
    unlimited).
-   **Download as ZIP** before deleting, per-file download links and
    per-row "physically missing" badges.
-   **Delete selected** or **Delete all filtered**. The bulk
    delete requires typing the exact file count to confirm.
-   Uses the file storage tree on the left, the same as the file list.

> [!WARNING]
> File Cleanup deletes physical files **and** their `sys_file` /
> `sys_file_reference` rows immediately. There is no undo. Double-check
> your filters before running a bulk delete.

## Duplicate report {#usage-duplicates}

**File > Filelist** → **Find duplicates** button in the toolbar
(admins only). Lists every group of files in the storage with identical content
(same `sys_file.sha1`) where at least one copy lies in the current folder
or below; the other copies are looked up in the whole storage.

-   **Only real copies count.** Each copy is checked on disk and sizes are read
    from disk; `sys_file.missing` and `sys_file.size` are not
    trusted. Records whose file is gone are left out and counted in the
    summary. Several `sys_file` records pointing to the same path count as
    one copy (their usages are added up).
-   **Sorted by wasted space** (`(copies − 1) × size`), 25 groups per page,
    with lazy-loaded thumbnails.
-   **Per copy:** path, file-level metadata (title, alternative, description),
    number of file references and soft references (for example `t3://file`
    links in RTE fields). Click the usage count to see each reference with
    edit links that return to the report.
-   **Suggested keeper** (star icon): the copy with the most usages, then the
    oldest one.
-   **Badges** when copies carry different file-level metadata or when soft
    references exist.
-   **CSV export** of the folder's groups: one row per file reference (or per
    copy without references).

### Deep check and delete {#usage-duplicates-deepcheck}

Each copy has a **Deep check** that searches the whole database live for
usages of that one file:

1.  `sys_file_reference` (every workspace and language),
1.  the reference index `sys_refindex` (relation fields, links in RTE/link
    fields, form definitions),
1.  a text search in every string/text/JSON column of every table for the
    public path (also URL-encoded), the combined identifier
    (`1:/path/file.jpg`), `t3://file?uid=N` and the legacy `file:N`
    syntax, exact-matched,
1.  other `sys_file` records indexing the same physical file.

Technical tables (caches, logs, history, `sys_file*`, `sys_refindex`,
sessions, `tx_filefix_*`) are skipped and listed. Usages by deleted records
are shown but do not block deletion. Text matches stop at 50.

Only when the check finds **zero active usages** does a **Delete file**
button appear. After a second confirmation the server runs the deep check
**again** and refuses (HTTP 409) if the file is in use. Deletion goes through
FAL (physical file, `sys_file`, metadata, processed files) and is written
to `tx_filefix_log` as `delete_duplicate`.

The report itself is read-only; nothing is merged or re-linked automatically.

## Oversized images {#usage-oversized}

**File > Filelist** → **Oversized images** button in the toolbar
(admins only). Lists images in the current folder (subfolders optional) whose
width or height exceeds the configured maximum, with the estimated saving if
resized to fit.

-   Maximum width/height from the [extension configuration](https://docs.typo3.org/permalink/anubit/filefix:extension-configuration@main) (default 1900 × 1900 px). Checked types:
    `jpg`, `jpeg`, `jfif`, `png`, `webp`, `tif`, `tiff`,
    `bmp` (`gif` is left out because it may be animated). Max width/height
    and **Include subfolders** can be changed in the report for that
    view only.
-   Dimensions come from `sys_file_metadata`; files are checked on disk and
    sizes read from disk. Images missing on disk or without known dimensions
    are left out and counted in the summary.
-   **Estimated saving** = `size × (new pixels / old pixels)`. Sorted by
    largest saving, 25 per page.

### Resize {#usage-oversized-resize}

1.  **Dry run**: the image is converted on the server, the result is
    measured and discarded. A modal shows before/after dimensions and size.
1.  **Resize now**: the server checks the file again and replaces it
    via FAL `replaceFile()`.

-   **Same file name, same** `sys_file` **uid, same format**: references,
    crops and links keep working. `size`, `sha1` and dimensions are
    updated; processed files are regenerated.
-   Resizes to the limits from the extension configuration (not the values
    typed into the report form), aspect ratio kept. JPEG quality follows
    `$GLOBALS['TYPO3_CONF_VARS']['GFX']['jpg_quality']`. The embedded
    colour profile is always kept.
-   The result is only kept when it is at least **10 KB** smaller.
-   Refused for: types other than `jpg`, `jpeg`, `png`; files indexed by
    more than one `sys_file` record; non-Local storage drivers; missing or
    non-writable files; images already within the limits.

> [!WARNING]
> Resizing overwrites the original file. There is **no backup and no entry
> in** `tx_filefix_log`. Back up `fileadmin` first if you may need
> the originals.

## Dashboard widgets {#usage-dashboard}

Requires [`typo3/cms-dashboard`](https://packagist.org/packages/typo3/cms-dashboard) (optional). Widget group
**filefix** with four widgets:

| Widget | Shows |
| --- | --- |
| Unused files | Number of unused files on disk |
| Reclaimable space | Disk space deleting them would free (for example `6.4 GB`) |
| Unused files by type | Doughnut chart by extension |
| Unused space by type | Same chart, by size |

Each physical file is counted once, only when **all** its `sys_file`
records are unused, only when it exists on disk, with its size read from disk.

The result is cached in `sys_registry` (namespace `tx_filefix`, key
`stats.storage.<uid>`) and rebuilt when older than **1 hour**, or on demand
via the schedulable [filefix:stats:update](https://docs.typo3.org/permalink/anubit/filefix:command-stats-update@main) command.
Widgets use the default storage.