Guetzli Deployment and Usage Guide

Prerequisites

System Requirements

Memory: 300MB of RAM per 1MPix of input image
CPU: Approximately 1 minute of CPU time per 1 MPix of input image
Operating Systems: Linux, Windows, or macOS

Required Libraries

libpng: Required for PNG input/output support
- Ubuntu/Debian: libpng-dev
- Fedora: libpng-devel
- Arch Linux: libpng
- Alpine Linux: libpng-dev
- macOS (Homebrew): libpng
- macOS (MacPorts): libpng

Development Tools

C++ Compiler: GCC or Clang for POSIX systems, Visual Studio 2015 for Windows
Build System: GNU Make (POSIX), Visual Studio (Windows), or Bazel (optional)

Installation

POSIX Systems (Linux, macOS)

Clone the repository:

git clone https://github.com/google/guetzli.git
cd guetzli

Install libpng:

# Ubuntu/Debian
sudo apt-get install libpng-dev

# Fedora
sudo dnf install libpng-devel

# Arch Linux
sudo pacman -S libpng

# Alpine Linux
sudo apk add libpng-dev

# macOS (Homebrew)
brew install libpng

# macOS (MacPorts)
sudo port install libpng

Build the binary:

make

The binary will be created at bin/Release/guetzli.

Windows

Clone the repository:

git clone https://github.com/google/guetzli.git

Install prerequisites:
- Visual Studio 2015
- vcpkg
Install libpng using vcpkg:

.\vcpkg install libpng

Integrate vcpkg packages system-wide:

.\vcpkg integrate install

Open the Visual Studio project and build it.

macOS (Alternative Method)

Clone the repository:

git clone https://github.com/google/guetzli.git
cd guetzli

Install libpng using Homebrew or MacPorts (see above).
Build the binary:

# If using Homebrew
make

# If using MacPorts
CFLAGS='-I/opt/local/include' LDFLAGS='-L/opt/local/lib' make

Using Bazel (Alternative)

Install Bazel: https://bazel.build
Build with Bazel:

bazel build -c opt //:guetzli

Configuration

Guetzli does not require any configuration files or environment variables. However, note the following:

Input Color Profile: Guetzli assumes input images are in sRGB profile with a gamma of 2.2
Color Profile Metadata: Guetzli will ignore any color-profile metadata in the input image
Alpha Channel: JPEG images do not support alpha channels. If input is a PNG with alpha, it will be overlaid on a black background before encoding

Build & Run

Local Development

Build the binary (see Installation section above)
Test with a sample image:

# Download sample image
wget https://github.com/google/guetzli/releases/download/v0/bees.png

# Encode the image
./bin/Release/guetzli --quality 85 --verbose bees.png output.jpg

Usage Examples

# Basic usage
guetzli original.png output.jpg
guetzli original.jpg output.jpg

# With quality parameter (equivalent to libjpeg quality)
guetzli --quality 90 original.png output.jpg

# With verbose output
guetzli --verbose original.png output.jpg

Input Recommendations

Preferred Input: Uncompressed images (PNG format) that haven't been previously compressed with any JPEG encoder
Supported Input Formats: PNG and JPEG
Quality Note: Guetzli is designed to work on high-quality images. Results will be poorer with already compressed images

Deployment

Standalone Binary

Since Guetzli is a command-line tool, you can deploy it as a standalone binary:

Build the binary on your target system (or cross-compile)
Copy the binary to your deployment location
Ensure libpng is installed on the target system

Docker Deployment

Create a Dockerfile for containerized deployment:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y libpng-dev

COPY guetzli /usr/local/bin/guetzli
COPY your_script.sh /usr/local/bin/your_script.sh

RUN chmod +x /usr/local/bin/guetzli
RUN chmod +x /usr/local/bin/your_script.sh

ENTRYPOINT ["your_script.sh"]

Cloud Platforms

Guetzli can be deployed on any cloud platform that supports Linux containers or virtual machines:

AWS: Deploy as EC2 instance or ECS container
Google Cloud: Deploy as Compute Engine VM or Cloud Run container
Azure: Deploy as Virtual Machine or Container Instance
Heroku: Deploy as container-based application

Web Service Wrapper

For web-based usage, you can create a simple web service wrapper:

# Example Flask wrapper
from flask import Flask, request, send_file
import subprocess
import tempfile

app = Flask(__name__)

@app.route('/compress', methods=['POST'])
def compress_image():
    file = request.files['image']
    with tempfile.NamedTemporaryFile(suffix='.png') as input_file, \
         tempfile.NamedTemporaryFile(suffix='.jpg') as output_file:
        file.save(input_file.name)
        subprocess.run(['guetzli', '--quality', '85', input_file.name, output_file.name])
        return send_file(output_file.name, mimetype='image/jpeg')

if __name__ == '__main__':
    app.run()

Troubleshooting

Common Issues

"libpng not found" error
- Solution: Install libpng development package for your OS
- Ubuntu/Debian: sudo apt-get install libpng-dev
- Fedora: sudo dnf install libpng-devel
Out of memory errors
- Guetzli requires 300MB per 1MPix of input
- Solution: Use smaller images or increase available memory
- Check input image dimensions: identify input.png
Slow processing
- Guetzli is intentionally slow (1 minute per 1MPix)
- Solution: Use lower quality settings or process images in batches
Build failures on Windows
- Ensure Visual Studio 2015 is installed
- Verify vcpkg integration: .\vcpkg integrate install
- Check that libpng was installed successfully with vcpkg
Poor compression results
- Guetzli works best with high-quality input images
- Solution: Provide uncompressed PNG input rather than already-compressed JPEGs
Alpha channel issues
- JPEG format doesn't support transparency
- Solution: Expect alpha channels to be composited on black background

Performance Tips

Use Guetzli on high-quality source images for best results
Process images in batches to amortize the overhead
Consider using lower quality settings (85-90) for web use
Monitor memory usage for large images

Quality Verification

After compression, verify the output quality:

# Compare file sizes
ls -lh original.png output.jpg

# Check image dimensions (should be identical)
identify original.png output.jpg

# Visual inspection
# Open both images in an image viewer to compare quality

How to Deploy & Use google/guetzli