On npm · Node.js 18+ · MIT

Convert images to WebP from your terminal

aywebp is a lightweight CLI that turns JPEG, PNG, GIF, TIFF, BMP, and WebP files into optimized .webp images — one file or entire folders, with sensible defaults and full control when you need it.

Get started Read the docs

Quick install

npm install -g aywebp

npmjs.com/package/aywebp Windows · macOS · Linux Powered by sharp

powershell — aywebp

$ aywebp ./photos -r -q 85

Converted: photos/hero.jpg → photos/hero.webp

Converted: photos/icons/logo.png → photos/icons/logo.webp

Warning: Skipped (exists): photos/banner.webp

Done: 2 converted, 1 skipped, 0 failed (3 total).

Features

Everything you need, nothing you don't

Built for developers who want smaller images without opening a GUI or writing a script from scratch.

Single file or batch

Point aywebp at one image or a whole directory. Perfect for quick saves or bulk asset pipelines.

Recursive folders

Use -r or --recursive to walk subdirectories and convert every supported image in one run.

Quality control

Default quality is 85. Dial it from 1–100 with -q to balance size and visual fidelity.

Resize on convert

Set -W / -H for width or height, or both with --fit. Aspect ratio is preserved by default.

Safe by default

Skips existing .webp files unless you pass --force. Originals stay unless you choose --delete-source.

Script-friendly

Clear exit codes and a summary line make aywebp easy to plug into CI, npm scripts, and shell pipelines.

Blazing fast

Uses sharp under the hood for native-speed encoding on every major platform.

Installation

Up and running in three steps

Requires Node.js 18 or newer. npm is included with Node.

Install from npm

One command — available on the npm registry.

npm install -g aywebp

Verify

Open a terminal and check the CLI is on your PATH.

aywebp --version

Convert

Point aywebp at a file or folder.

aywebp photo.png
aywebp ./images -r

Alternative: npm install -g github:kakajan/AyWebP

CLI reference

Simple commands, full control

Output is always written beside the source: photo.jpg becomes photo.webp in the same folder.

Common commands

aywebp photo.png
aywebp ./images -r
aywebp photo.png -W 1200 -H 800
aywebp ./assets -q 80 -f -d

Option	Short	Default	Description
`--quality`	`-q`	85	WebP quality from 1 (smallest) to 100 (best)
`--recursive`	`-r`	off	Scan subdirectories when path is a folder
`--force`	`-f`	off	Overwrite existing `.webp` output files
`--delete-source`	`-d`	off	Delete source after successful conversion
`--width`	`-W`	—	Resize to width in pixels
`--height`	`-H`	—	Resize to height in pixels
`--fit`	—	inside	When width and height are set: inside, cover, fill, outside
`--enlarge`	—	off	Allow upscaling smaller images

AI / MCP

Use with Cursor, Claude Code, Codex, and more

aywebp-mcp exposes structured tools for AI agents — convert, inspect, and preview images with path sandboxing. Works with any MCP-compatible IDE or CLI.

4 MCP tools

convert_images, inspect_image, list_convertible, get_version

Path sandbox

Set AYWEBP_ALLOWED_ROOTS so agents only access folders you allow.

Multi-IDE configs

Ready-to-copy setup for Cursor, Claude Code, OpenCode, Codex, Windsurf, and Cline.

Global MCP install

npm install -g aywebp
# then add aywebp-mcp to your IDE — see examples/mcp-configs/

MCP config examples · Full MCP docs

Formats

Supported input formats

All inputs convert to .webp in the same directory.

.jpg / .jpeg .png .gif .tif / .tiff .bmp .webp (re-encode)

Star it on GitHub

If aywebp saves you time or disk space, a star helps other developers discover it. Issues and pull requests are welcome.

Install from npm View on GitHub