Using Snappy (wkhtmltopdf) on Laravel Cloud: A Complete Guide

Running wkhtmltopdf on managed platforms is rarely straightforward, and Laravel Cloud is no exception, especially now that Cloud environments run on ARM64 (aarch64).

In this post, I’ll walk through exactly how to get Snappy working on Laravel Cloud, the errors you will encounter, why they happen, and the production-safe solution that actually works.

This guide assumes you are already familiar with Laravel and PDF generation using barryvdh/laravel-snappy.

The problem: Snappy works locally, fails on Laravel Cloud

On a typical VM or Docker container, installing wkhtmltopdf is easy:

apt install wkhtmltopdf

On Laravel Cloud, this fails immediately.

Why?

Because Laravel Cloud does not allow root access or OS package installation. Any attempt to use apt, yum, or apk will result in permission errors.

That means:

• You cannot install wkhtmltopdf system-wide
• You cannot install missing shared libraries
• You must treat the environment as immutable

Step 1: Install Snappy (the easy part)

Snappy itself installs normally via Composer:

composer require barryvdh/laravel-snappy
php artisan vendor:publish --provider="Barryvdh\Snappy\ServiceProvider"

At this point, your application will still fail when generating PDFs — because Snappy is only a wrapper. The real work is done by the wkhtmltopdf binary.

Step 2: Understand Laravel Cloud’s architecture (critical)

Laravel Cloud runs on ARM64 (aarch64) infrastructure.

You can verify this with:

uname -m

Output:

aarch64

This is extremely important.

Most common wkhtmltopdf binaries — including the popular h4cc/wkhtmltopdf-amd64 Composer package is built for x86_64, not ARM.

Trying to run them results in:

Exec format error (exit code 126)

Step 3: Download the correct wkhtmltopdf binary (ARM64)

You must download a Linux ARM64 build of wkhtmltopdf.

From the official site: https://wkhtmltopdf.org/downloads.html

Example file:

wkhtmltox-0.12.6-1.linux-arm64.tar.xz

Extract it locally and copy the binaries into your Laravel project:

mkdir -p storage/bin
cp wkhtmltox/bin/wkhtmltopdf storage/bin/wkhtmltopdf
cp wkhtmltox/bin/wkhtmltoimage storage/bin/wkhtmltoimage

Commit these files to your repository.

Yes, they are large (~40MB). This is expected.

Step 4: Configure Snappy to use your bundled binary

Update config/snappy.php:

'pdf' => [
    'enabled' => true,
    'binary'  => base_path('storage/bin/wkhtmltopdf'),
    'timeout' => false,
    'options' => [
        'enable-local-file-access' => true,
    ],
],

At this stage, wkhtmltopdf will execute — but you will likely hit another error.

Step 5: Fix missing shared libraries (the real challenge)

When running:

storage/bin/wkhtmltopdf --version

You may see:

error while loading shared libraries: libjpeg.so.8: cannot open shared object file

This happens because the wkhtmltopdf binary is dynamically linked, and Laravel Cloud does not include some legacy libraries by default.

You cannot install them with apt.

So what do you do?

You bundle the shared library yourself.

Step 6: Bundle libjpeg.so.8 with your app

Create this directory:

storage/lib/aarch64/

Download libjpeg.so.8 for ARM64 Linux (for example, by extracting it from an ARM64 Ubuntu container) and place it here:

storage/lib/aarch64/libjpeg.so.8

Commit it to your repository.

Step 7: Tell Snappy where to find bundled libraries

Update config/snappy.php again:

'pdf' => [
    'enabled' => true,
    'binary'  => base_path('storage/bin/wkhtmltopdf'),
    'timeout' => false,
    'options' => [
        'enable-local-file-access' => true,
    ],
    'env' => [
        'LD_LIBRARY_PATH' => base_path('storage/lib/aarch64'),
    ],
],

This is the key fix.

It instructs the dynamic loader to resolve missing .so files from your application directory.

Step 8: Laravel Cloud build commands (don’t skip this)

In Laravel Cloud → Build Commands, add:

chmod +x storage/bin/wkhtmltopdf
chmod +x storage/bin/wkhtmltoimage || true

php artisan config:clear
php artisan config:cache

Do not put this in Deploy commands — only Build persists filesystem changes.

Step 9: Verify everything

Run:

ldd storage/bin/wkhtmltopdf | grep "not found" || true
storage/bin/wkhtmltopdf --version

If:

• ldd shows nothing missing
• --version prints successfully

🎉 Snappy is now fully functional on Laravel Cloud.

Final notes and recommendations

• This setup works and is production-safe
• However, wkhtmltopdf is fragile on managed platforms
• For high-volume or complex PDFs, consider:
• Offloading PDF generation to a worker you control
• Or using a Chromium-based renderer (e.g., Gotenberg)

Still, if you want Snappy on Laravel Cloud, this is the correct and proven way to do it.

Conclusion

Using Snappy on Laravel Cloud requires:

• ARM64 awareness
• Bundling binaries instead of installing packages
• Managing shared libraries manually

Once you understand these constraints, the solution is straightforward.

Hopefully, this saves you several hours of debugging.

Happy building.