README

Laravel Cloud Binaries

Pre-built static binaries for Laravel Cloud. Ready in vendor/bin, no system packages required.

Note

This is an independent, community package. It is not an official or first-party Laravel package, and is not affiliated with, endorsed by, or sponsored by Laravel or Laravel Cloud. "Laravel" is a trademark of its respective owner.

Pre-built, statically compiled binaries for Linux (arm64/musl). Designed to be installed as a Composer package so that vendor/bin/ contains ready-to-use tools on Laravel Cloud (or any Linux arm64 environment).

This package includes all the binaries required by spatie/image-optimizer, making it a drop-in solution for image optimization on environments where system packages are not available. Note that svgo is not included as it is a regular npm package and can be installed via npm install -g svgo.

Beyond image optimization, it also ships ffmpeg/ffprobe for media, zstd for compression, and qpdf for PDF manipulation.

Binaries included

Binary	Purpose
`jpegoptim`	JPEG optimization
`optipng`	PNG optimization
`pngquant`	PNG lossy compression
`cwebp`	WebP encoding
`dwebp`	WebP decoding
`avifenc`	AVIF encoding
`avifdec`	AVIF decoding
`gifsicle`	GIF optimization
`ffmpeg`	Audio/video transcoding
`ffprobe`	Media stream analysis
`magick`	ImageMagick 7 (replaces convert/identify/mogrify)
`zstd`	Zstandard compression/decompression
`qpdf`	PDF transformation (merge, split, encrypt, linearize)

All binaries are statically linked against musl libc (Alpine Linux) and built for arm64 (aarch64). They will not run on macOS, nor on x86-64 (amd64) Linux hosts — this is expected.

Pinned versions

All upstream versions are defined at the top of the Makefile and passed to each Dockerfile via --build-arg. To bump a version, change the single variable in the Makefile.

Binary	Variable	Current version	Size
jpegoptim	`JPEGOPTIM_VERSION`	`v1.5.6`	642 KB
optipng	`OPTIPNG_VERSION`	`0.7.8`	386 KB
pngquant	`PNGQUANT_VERSION`	`3.0.3`	1.1 MB
cwebp	`LIBWEBP_VERSION`	`v1.5.0`	1.1 MB
dwebp	`LIBWEBP_VERSION`	`v1.5.0`	834 KB
avifenc	`LIBAVIF_VERSION`	`v1.2.1`	6.8 MB
avifdec	`LIBAVIF_VERSION`	`v1.2.1`	6.7 MB
gifsicle	`GIFSICLE_VERSION`	`v1.96`	323 KB
ffmpeg	`FFMPEG_VERSION`	`n7.1.1`	29 MB
ffprobe	`FFMPEG_VERSION`	`n7.1.1`	29 MB
magick	`IMAGEMAGICK_VERSION`	`7.1.1-43`	7.8 MB
zstd	`ZSTD_VERSION`	`v1.5.7`	1.5 MB
qpdf	`QPDF_VERSION`	`v12.4.0`	3.3 MB
Total			88 MB

Installation

composer require mathiasgrimm/laravel-cloud-binaries

Composer will symlink all 13 binaries into vendor/bin/.

Selective installation (faster deploys)

If you only need a few binaries, you can install the package as a dev dependency, copy just the ones you need into your repository, and avoid downloading the full ~88 MB on every deploy:

composer require --dev mathiasgrimm/laravel-cloud-binaries

# Copy only the binaries you need into your project
mkdir -p bin
cp vendor/bin/jpegoptim bin/
cp vendor/bin/optipng bin/
cp vendor/bin/pngquant bin/

# Commit them
git add bin/
git commit -m "Add image optimization binaries"

Then reference them from your application using base_path('bin/jpegoptim') (or whichever path you chose). Since the binaries are committed to your repository, they are available immediately during deployment with no Composer overhead.

To keep your committed binaries in sync automatically when the package is updated, add a post-update-cmd script to your composer.json:

{
    "scripts": {
        "post-update-cmd": [
            "@php -r \"@mkdir('bin', 0755, true);\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/jpegoptim', 'bin/jpegoptim');\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/optipng', 'bin/optipng');\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/pngquant', 'bin/pngquant');\""
        ]
    }
}

After every composer update, the selected binaries are copied into bin/ automatically. Adjust the list to include only the binaries you need. The @php -r syntax ensures the commands work on all platforms (Linux, macOS, and Windows).

Prefer not to ship binaries at all?

This package runs optimization on your own infrastructure, which is the right trade-off when you want no external dependency and no per-image cost.

If you would rather not ship ~88 MB of executables, Glimpse does the same kind of work — optimize, convert, resize, thumbnail — over an HTTP API, with a CLI and a PHP SDK and nothing to compile:

composer require mathiasgrimm/glimpse-cli

glimpse optimize public/images/hero.png --in-place
glimpse convert public/images/hero.png --format=avif --optimize -i

The trade-off is the obvious one: images are processed by a third-party service rather than locally, so it needs network access, and anything beyond the analyze/check endpoints requires an API token. Pick whichever fits — locally executed binaries, or a managed API.

This repository uses Glimpse itself, in CI, to keep its own banner optimized.

Usage

After installation, the binaries are available in vendor/bin/:

vendor/bin/jpegoptim --strip-all image.jpg
vendor/bin/optipng -o2 image.png
vendor/bin/pngquant --quality=65-80 image.png
vendor/bin/cwebp -q 80 image.png -o image.webp
vendor/bin/dwebp image.webp -o image.png
vendor/bin/avifenc image.png image.avif
vendor/bin/avifdec image.avif image.png
vendor/bin/gifsicle -O3 animation.gif -o optimized.gif
vendor/bin/ffmpeg -i input.mp4 -c:v libx264 output.mp4
vendor/bin/ffprobe -v quiet -print_format json -show_format input.mp4
vendor/bin/magick input.png -resize 50% output.png
vendor/bin/zstd -19 backup.sql -o backup.sql.zst
vendor/bin/zstd -d backup.sql.zst
vendor/bin/qpdf --linearize input.pdf output.pdf
vendor/bin/qpdf --empty --pages a.pdf b.pdf -- merged.pdf

Note: These are statically compiled Linux arm64 (musl) binaries. They will work on Laravel Cloud and other Linux arm64 environments but not on macOS, Windows, or x86-64 Linux.

Building from source

Prerequisites

Docker
make

Build all binaries

make

Binaries are output to the bin/ directory.

Each Dockerfile builds for the host architecture, so run the build on an arm64 machine (Apple Silicon, or any aarch64 Linux host) to match the architecture of the committed binaries. Builds are not byte-for-byte reproducible — the Dockerfiles track alpine:latest and unpinned apk packages, so only the upstream tool version is pinned. To build for a different architecture, pass --platform through Docker — e.g. docker build --platform linux/amd64 ... — bearing in mind that emulated builds are considerably slower.

Build a single binary

make bin/jpegoptim
make bin/optipng
make bin/pngquant
make bin/cwebp
make bin/dwebp
make bin/avifenc
make bin/avifdec
make bin/gifsicle
make bin/ffmpeg
make bin/ffprobe
make bin/magick
make bin/zstd
make bin/qpdf

Parallel builds

make -j4

Testing

Verify that all binaries work correctly by running them inside an Alpine Docker container:

make test          # build (if needed) + test
make test-only     # test without rebuilding

Clean up

make clean          # remove bin/ contents
make clean-images   # remove Docker images
make clean-all      # both

Licensing

The MIT license in LICENSE covers only this repository's build scripts and documentation. The binaries in bin/ are built from third-party projects and keep their own licenses — jpegoptim, pngquant, gifsicle, ffmpeg, and ffprobe are GPL. ffmpeg/ffprobe are built with --enable-gpl, --enable-libx264, and --enable-libx265, which per FFmpeg's own LICENSE.md changes its license from LGPL-2.1+ to GPL-2.0+.

qpdf is Apache-2.0. It carries an upstream NOTICE file, reproduced in licenses/qpdf-NOTICE.txt, which redistributors must pass along. It also contains code derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm, whose license requires exactly that identification wherever the derived work is referenced — see licenses/RSA-MD.txt.

If you are only using these binaries in your own application, the GPL imposes no obligations on you — running a program is not distribution. If you redistribute them, whether directly or bundled into a product you ship, read THIRD-PARTY-NOTICES.md first. It lists the license for every binary and its statically linked components, and includes the corresponding-source offer.

Full license texts are in licenses/.

How it works

Each tool has its own Dockerfile under <tool>/Dockerfile. The Dockerfiles use multi-stage Alpine builds:

Builder stage — installs dependencies, clones source, compiles with static linking flags, then strips symbol tables (these are shipped artifacts, not debugging targets)
Final stage — FROM scratch, copies only the static binary

The Makefile orchestrates building the Docker images and extracting the binaries into bin/.

mathiasgrimm / laravel-cloud-binaries

Maintainers

Package info

Statistics

Security