How to Specify Output Format for Processed Images in ImageKit

Use the --output-format CLI flag followed by the desired format (jpg, png, webp, gif, or bmp) to force a specific output encoding regardless of the input file extension.

When batch processing images with the open-source hzbd/imagekit Rust tool, controlling the destination file type is critical for web optimization and cross-platform compatibility. This guide explains how to specify output format for processed images in ImageKit using both command-line arguments and programmatic configuration, based on the actual implementation in the source code.

Understanding the OutputFormat Enum

The format selection logic begins in [src/cli.rs](https://github.com/hzbd/imagekit/blob/master/src/cli.rs), where the OutputFormat enum defines the available encoding options. According to the source code at lines 108-116, the enum supports five variants:

• Jpg
• Png
• Webp
• Gif
• Bmp

These variants implement a conversion to the image::ImageFormat type from the underlying image crate. When the CLI parses the --output-format argument, it maps the string input to the corresponding enum variant, which later drives the encoding decision in the processing pipeline.

Using the --output-format CLI Flag

To force a specific output format for all processed images, append the flag to your command:

# Convert all JPEGs to PNG while resizing to 800px width

./target/release/imagekit \
    -i example/img-src \
    -o example/img-out \
    --width 800 \
    --output-format png

This command overrides the original file extensions and saves every processed image as a PNG file. The tool automatically assigns the correct extension (.png, .jpg, .webp, etc.) based on the selected format.

Internal Format Selection Logic

The core decision logic resides in [src/processor.rs](https://github.com/hzbd/imagekit/blob/master/src/processor.rs) within the process_image function (lines 51-60). The implementation checks whether cli.output_format contains a value:

• If specified: The chosen ImageFormat is used, and the output filename is generated with the corresponding extension.
• If omitted: The system falls back to ImageFormat::from_path, preserving the original file's extension.

After format determination, the save_image_with_format function (lines 95-107) handles the actual encoding. This function selects the appropriate encoder for the target format—applying JPEG quality settings or using lossless PNG compression—and writes the final file to the output directory.

Programmatic Configuration in Rust

For custom tooling that invokes ImageKit's core logic directly, you can construct a Cli instance with the output_format field set explicitly:

use imagekit::cli::{Cli, OutputFormat};
use std::path::PathBuf;

let cli = Cli {
    input_dir: PathBuf::from("example/img-src"),
    output_dir: PathBuf::from("example/img-out"),
    width: Some(800),
    height: None,
    watermark_text: None,
    watermark_position: Default::default(),
    font_size: 24,
    watermark_color: Default::default(),
    quality: 85,
    output_format: Some(OutputFormat::Webp), // Force WebP output
};

When this configuration is passed to process_image, the code path at src/processor.rs:51-60 selects WebP as the target format, ensuring all output files receive the .webp extension and encoding.

Summary

• Use --output-format followed by jpg, png, webp, gif, or bmp to force a specific encoding.
• Default behavior preserves the original file extension when no format flag is provided.
• Source locations: Format parsing occurs in src/cli.rs (lines 108-116), while selection logic lives in src/processor.rs (lines 51-60 and 95-107).
• Extensions are automatic: The tool appends the correct file extension based on the chosen OutputFormat variant.

Frequently Asked Questions

What happens if I omit the --output-format flag?

If you do not specify the output format, ImageKit defaults to preserving the original file's extension. The system calls ImageFormat::from_path on the input filename to determine the encoding, maintaining the source format unless resizing or other processing requires re-encoding.

Which image formats does ImageKit support for output?

According to the OutputFormat enum defined in src/cli.rs, ImageKit supports JPEG, PNG, WebP, GIF, and BMP. These cover the most common web and archival image formats, with WebP recommended for web applications requiring smaller file sizes.

Does specifying an output format affect image quality?

Yes, the output format interacts with quality settings defined in the Cli struct. When converting to JPEG, the quality parameter (default 85) controls compression levels. PNG output uses lossless compression regardless of quality settings, while WebP respects quality settings for lossy encoding but supports lossless modes depending on the source image characteristics.

Can I convert a mixed directory of formats to a single output type?

Absolutely. The --output-format flag forces uniform output encoding across all processed files. Whether your input directory contains JPEGs, PNGs, or GIFs, specifying --output-format webp (for example) ensures every output file is encoded as WebP with the correct .webp extension, as handled by the save_image_with_format function in src/processor.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}