img2numpy Install

Open-source Python SDK

Convert images into NumPy arrays with one import.

img2numpy turns common image inputs into numpy.ndarray values for computer vision, ML preprocessing, notebooks, and batch pipelines.

pip install img2numpy
Layered image thumbnails transforming into a structured array grid
1-line import convert(image) returns an array.
Batch ready Directories, globs, iterables, and mixed sources.
Library first Import it directly inside scripts, apps, notebooks, and pipelines.

Quickstart

Pass an image. Get an array.

The default SDK path is intentionally small: import convert, pass a supported image source, and receive a numpy.ndarray.

  • Accepts file paths, bytes, file-like objects, PIL images, and URLs.
  • Supports channel conversion, normalization, dtype casting, resizing, and frames.
  • Keeps detailed metadata available through convert_result().
from img2numpy import convert

array = convert("frame.png")

print(array.shape)
print(array.dtype)
from img2numpy import convert_many

batch = convert_many("images/*.jpg")

for result in batch.results:
    if result.ok:
        print(result.source, result.shape)
from img2numpy import ConversionOptions, convert

options = ConversionOptions(
    channel_mode="RGB",
    normalize_mode="0..1",
    dtype="float32",
    resize=(224, 224),
)

array = convert("sample.webp", options=options)

Format coverage

Built for popular image workflows.

The SDK reports decoder capabilities at runtime. Core raster formats are available by default, while advanced formats are represented as optional backends.

PNG

Lossless raster images with alpha support.

JPEG

Standard photo and dataset image format.

WEBP

Modern web images with lossy and lossless modes.

GIF

Static and animated frames with frame="all".

BMP

Simple bitmap inputs for legacy pipelines.

TIFF

Multi-page and scientific imaging workflows.

HEIF / HEIC

Phone camera formats through optional decoder support.

AVIF

High-compression image assets when the backend is present.

SVG / PDF

Rendered to pixels, then returned as arrays.

RAW

Camera raw families through optional raw decoding.

SDK reference

A small surface area with room to grow.

convert(source, options=None)

Returns a numpy.ndarray. This is the default path for users who just need pixels.

convert_result(source, options=None)

Returns ConversionResult with array, shape, dtype, source, format, and metadata.

convert_many(sources, fail_fast=False)

Expands folders, globs, and iterables into per-file conversion results.

save_npz() and load_npz()

Write and read compressed NumPy artifacts using the project manifest convention.

decoder_capabilities()

Reports which format backends are available in the current environment.

Inside your code

Import it where image data enters your program.

The core product is a normal Python package. Use it in a training script, image preprocessing module, notebook, CLI tool, desktop app, or backend worker as a plain function call. 

# preprocess.py
from pathlib import Path

from img2numpy import ConversionOptions, convert

options = ConversionOptions(
    channel_mode="RGB",
    normalize_mode="0..1",
    dtype="float32",
)

def load_frame(path: str | Path):
    return convert(path, options=options)

frame = load_frame("dataset/cat.png")
print(frame.shape)

Open source alpha

Designed for people who need arrays, not ceremony.

Start with the one-line SDK, then opt into batch conversion, metadata, and NPZ helpers only when your pipeline needs them.

Try the SDK