Boost Lighthouse Scores Instantly: Convert Images to WebP with img2webp

img2webp is a command-line tool and GitHub Action that converts images to the modern WebP format. It helps you improve your site’s performance, Core Web Vitals, and Lighthouse scores by reducing image file sizes by 30–70% without noticeable quality loss.

Find it on the GitHub Marketplace: img2webp

#Why WebP and Lighthouse?

Lighthouse measures your page’s performance, and one of the most critical metrics is Largest Contentful Paint (LCP). For many pages, the LCP element is a large image (like a hero banner or product photo). Heavy, unoptimized images directly lower your Lighthouse score. By serving lighter WebP images, you reduce load times and improve your performance grades.

img2webp automates the conversion and integrates seamlessly into your workflow. This tutorial covers local CLI usage on Ubuntu and automated CI with GitHub Actions.

#Local Installation and Testing on Ubuntu

#Step 1: Install Go (golang-go)

If you don’t have Go installed, install it via apt:

sudo apt update
sudo apt install golang-go -y

Verify Go version (should be 1.26.2+ – if older, download from go.dev):

go version

#Step 2: Install libwebp-dev (required for encoding)

sudo apt install libwebp-dev -y

Note: The webp package from apt contains tools like cwebp – but you need libwebp-dev for the Go binding that img2webp uses.

#Step 3: Install img2webp CLI

go install github.com/adnenre/img2webp@latest

#Step 4: Add ~/go/bin to your PATH

Go installs binaries in ~/go/bin. Add this directory to your shell’s PATH:

echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
source ~/.bashrc

Now verify that img2webp is accessible:

img2webp --help

If you see the help text, installation succeeded.

#Step 5: Navigate to Your Existing Project (React, Angular, or Vue)

Go to your real project root – the one that already contains a public/ or src/assets/ folder.

For example:

cd ~/my-react-app # React (CRA, Vite, Next)
cd ~/my-angular-app # Angular
cd ~/my-vue-app # Vue

Important: Your images should be inside public/images/ or src/assets/images/. The tool will scan recursively, so any subfolder works.

#Step 6: Dry Run – Preview Changes

Always preview before making changes. The --dry-run flag shows what would happen.

img2webp --input ./public --dry-run --verbose

Sample output would list every image that would be converted (e.g., public/images/logo.png -> public/images/logo.webp). No files are modified.

#Step 7: Convert Images

Run the actual conversion. This converts all PNG/JPEG in ./public to WebP with 85% quality (default is 75). Originals are deleted unless you add --keep-original true.

img2webp --input ./public --quality 85

#Step 8: Verify Results

ls public/images/

You should see .webp files. Also check that your HTML/CSS references were updated to .webp (if you haven’t disabled --update-refs, which is on by default).

#Step 9: Serve Your Project Locally

Start your dev server:

• React: npm start
• Angular: ng serve
• Vue: npm run dev

Your browser will now load WebP images. Open DevTools → Network tab to confirm smaller file sizes.

#CLI Options Reference

#Notes

• --replace controls whether image references in source files are rewritten.
• --dry-run allows safe preview without modifying files.
• Only .png, .jpg, .jpeg files are processed.
• Output format is always .webp.

#Automate with GitHub Actions (CI)

Add the workflow below to .github/workflows/img2webp-optimize.yml.

This GitHub Actions workflow automatically optimizes image assets by converting PNG/JPEG files to WebP format on every push to the main branch. It uses the img2webp CLI tool to scan the project’s ./public directory, generate WebP versions of images, and rewrite file references across the codebase when needed.

After optimization, the workflow commits any updated or newly generated WebP assets back into the repository, ensuring that the main branch always contains optimized production-ready images

name: Optimize Images to WebP

on:
  push:
    branches: [main]

jobs:
  optimize:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install img2webp
        run: go install github.com/adnenre/img2webp@latest

      - name: Convert images to WebP
        run: |
          img2webp \
            --input ./public \
            --quality 85 \
            --replace true \
            --v true

      - name: Commit optimized assets
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git add .
          git commit -m "chore: optimize images to WebP" || echo "No changes"
          git push

Why this helps Windows users: You commit your original PNG/JPEGs. The Action runs on GitHub’s Ubuntu runner, does the conversion, and your built site serves WebP. No local installation needed on Windows.

#Next Steps

• Run locally on Ubuntu/WSL to test on your real project.
• Add the GitHub Action to your CI pipeline.
• For Windows, rely on the Action or use WSL for local testing.

For full details, see the img2webp GitHub repository and the Go package documentation.

#GitHub Marketplace

You can find and use the official img2webp GitHub Action directly from the GitHub Marketplace. This action integrates into your CI/CD pipeline to automatically optimize images and update references as part of your build process.

#Conclusion

One command and boom – your images are WebP, your Lighthouse scores improve, and your users enjoy faster pages. Works on Ubuntu, WSL, and CI. No more manual image optimization.