webp-convert 1.0.0

Automatically convert PNG/JPG images to WebP with responsive sizes. CLI, file watcher, and Python API.

webp-convert (Python)

Automatically convert PNG/JPG/GIF/TIFF images to WebP with responsive size variants. Zero-config CLI, file watcher, and programmatic Python API.

---

Install

pip3 install webp-convert

Requires Python 3.8+. Uses Pillow — no external binaries required.

---

Quick start

# Convert everything in assets/images (default)
webp-convert

# Custom dir + quality
webp-convert src/img -q 90

# Watch mode — auto-converts on file change
webp-convert src/img --watch

# Custom responsive sizes
webp-convert src/img --sizes 1200,800,400

# Write outputs to a separate directory
webp-convert src/img -o dist/img

---

CLI reference

Usage: webp-convert [INPUT_DIR] [OPTIONS]

  Convert PNG/JPG images to WebP with responsive size variants.

Options:
  -o, --output TEXT       Output directory (default: same as source)
  -q, --quality INT       WebP quality 0-100  [default: 80]
      --lossless          Lossless encoding
      --sizes W,W,...     Responsive widths e.g. 1200,800,400 (0=full)
      --no-full           Skip full-size, only responsive variants
  -r, --recursive         Recurse into subdirectories
      --no-overwrite      Skip files that already have a .webp counterpart
  -w, --watch             Watch mode
      --silent            Suppress all output
  -h, --help              Show this message and exit

---

Programmatic API

from webp_convert import convert, watch, convert_file, ConvertConfig, SizeSpec

# --- Convert a directory (keyword args shortcut) ---
results = convert(input="src/images", quality=85)

# --- Convert with a config object ---
cfg = ConvertConfig(
    input="src/images",
    output="public/images",  # omit to write next to originals
    quality=85,
    lossless=False,
    recursive=True,
    overwrite=True,
    sizes=[
        SizeSpec(width=0,    suffix=""),       # full size
        SizeSpec(width=1200, suffix="-1200"),
        SizeSpec(width=800,  suffix="-800"),
        SizeSpec(width=400,  suffix="-400"),
    ],
    on_file=lambda r: print(f"{r.src} → {r.dest} ({r.size_bytes} bytes)"),
)
results = convert(cfg)

# --- Convert a single file ---
results = convert_file("hero.png", cfg)

# --- Watch mode (context manager) ---
import time
watcher = watch(ConvertConfig(input="src/images")).start()
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    watcher.stop()

---

Output structure

Given hero.jpg in src/images/:

src/images/
├── hero.jpg          (original, kept by default)
├── hero.webp         (full size)
├── hero-800.webp     (800px wide, aspect-ratio preserved)
└── hero-400.webp     (400px wide)

---

HTML usage

<picture>
  <source
    type="image/webp"
    srcset="hero-400.webp 400w, hero-800.webp 800w, hero.webp 1600w"
    sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1600px"
  />
  <img src="hero.jpg" alt="Hero image" />
</picture>

---

License

MIT