# How to Specify Output Format for Processed Images in ImageKit

> Control your image output! Learn how to specify image format in ImageKit using the CLI flag for JPG, PNG, WEBP, GIF, and BMP to ensure consistent encoding.

- Repository: [hzbd/imagekit](https://github.com/hzbd/imagekit)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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/main/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:

```bash

# 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/main/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:

```rust
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`](https://github.com/hzbd/imagekit/blob/main/src/cli.rs) (lines 108-116), while selection logic lives in [`src/processor.rs`](https://github.com/hzbd/imagekit/blob/main/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`](https://github.com/hzbd/imagekit/blob/main/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`](https://github.com/hzbd/imagekit/blob/main/src/processor.rs).