---
title: "Installation"
manual: "Image Optimization for TYPO3"
version: "2.6"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-image-optimize:installation@2.6"
source: "Installation/Index.rst"
rendered: "2026-09-25T11:13:49+00:00"
---

# Installation {#installation}

## Via Composer (recommended) {#installation-composer}

**Install the extension via Composer**

```bash
composer require netresearch/nr-image-optimize
```

## Manual installation {#installation-manual}

1.  Download the extension from the
    [TYPO3 Extension Repository](https://extensions.typo3.org/extension/nr_image_optimize).
1.  Upload to `typo3conf/ext/`.
1.  Activate the extension in the Extension Manager.

## Setup {#installation-setup}

The extension works out of the box after installation:

-   The frontend middleware picks up any request to the
    `/processed/` path and produces a variant on demand.
-   The PSR-14 event listener for
    `AfterFileAddedEvent` and `AfterFileReplacedEvent`
    runs on every new or replaced image.

No additional configuration is required.

> [!TIP]
> For best results, ensure that your server has the
> **Imagick** or **GD** PHP extension installed. The
> backend maintenance module can verify all prerequisites
> for you (see [System requirements check](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:maintenance-system-requirements@2.6)).

## Optional: install optimizer binaries {#installation-optional-binaries}

The automatic on-upload compression and the
[nr:image:optimize](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:usage-cli-optimize@2.6) CLI command call
out to `optipng`, `gifsicle`, and `jpegoptim`. The
[nr:image:analyze](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:usage-cli-analyze@2.6) command is purely
heuristic and does not require these binaries.

Install whichever tools you need and make them available in
`$PATH`:

**Debian/Ubuntu**

```bash
sudo apt-get install optipng gifsicle jpegoptim
```

**macOS (Homebrew)**

```bash
brew install optipng gifsicle jpegoptim
```

To pin a specific path (useful in containerized environments)
set one or more of the following environment variables:

-   **`OPTIPNG_BIN`**

    Absolute path to `optipng`.

-   **`GIFSICLE_BIN`**

    Absolute path to `gifsicle`.

-   **`JPEGOPTIM_BIN`**

    Absolute path to `jpegoptim`.

A set-but-invalid override is authoritative: the tool is
reported unavailable. There is no silent fallback to `$PATH`.

> [!TIP]
> If no supported binary is installed, the on-upload
> listener skips optimization silently. The
> `nr:image:optimize` CLI command, by contrast, reports
> the missing tools and exits with failure so an operator
> running a bulk job gets immediate feedback.
> `nr:image:analyze` works regardless because it never
> invokes an external binary.