imagesize

library2.0.1pypypi✓ verified 24d ago

The `imagesize` library is a pure Python module that efficiently extracts image dimensions, DPI, and other metadata (color depth, channel count, rotation) directly from image file headers, without needing to load the full image data. It supports a wide range of formats including BMP, PNG, JPEG, JPEG2000, GIF, TIFF, SVG, Netpbm, WebP, AVIF, HEIC, and HEIF. The current version is 2.0.0. It has a somewhat active release cadence, with recent updates in early March 2026.

serialization data

pip install imagesize

github ↗package ↗

INSTALL

IMPORT

SIG · IMAGESIZE

imagesize

serializationpythonv2.0.1

Install

1.5s avg

Import

129ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.134s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.124s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

imagesize

✓ import imagesize

get

✓ import imagesize width, height = imagesize.get('image.png')

getDPI

✓ import imagesize xdpi, ydpi = imagesize.getDPI('image.png')

get_info

✓ import imagesize info = imagesize.get_info('image.png')

This quickstart demonstrates how to use `imagesize.get()`, `imagesize.getDPI()`, and `imagesize.get_info()` to retrieve dimensions, DPI, and other metadata from an image file. It includes creating a minimal dummy PNG file for a runnable example.

import imagesize import os # Create a dummy image file for demonstration with open('test_image.png', 'wb') as f: f.write(b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\x0cIDATx\xda\xed\xc1\x01\x01\x00\x00\x00\xc2\xa0\xf7Om\x00\x00\x00\x00IEND\xaeB`\x82') # Get basic image dimensions width, height = imagesize.get('test_image.png') print(f"Width: {width}, Height: {height}") # Get DPI information (if available) xdpi, ydpi = imagesize.getDPI('test_image.png') print(f"X-DPI: {xdpi}, Y-DPI: {ydpi}") # Get comprehensive image information info = imagesize.get_info('test_image.png') print(f"Image Info: Width={info.width}, Height={info.height}, Rotation={info.rotation}, X-DPI={info.xdpi}, Y-DPI={info.ydpi}, Colors={info.colors}, Channels={info.channels}") # Clean up the dummy file os.remove('test_image.png')

Debug

Known issues

breakingIn version 2.0, `imagesize.get()` and `imagesize.getDPI()` no longer raise an exception on parsing failures. Instead, they now return `(-1, -1)`. Code that relied on exceptions for error handling will need to be updated to explicitly check for these return values.

fix

Update error handling logic to check for `(-1, -1)` as a return value from `imagesize.get()` and `imagesize.getDPI()` instead of catching exceptions.

affects: >=2.0.0

gotchaWhen using `imagesize.get()`, EXIF orientation metadata is applied by default for rotated JPEG/TIFF images, meaning the returned width and height reflect the visually oriented image. If you need the raw stored size, you must explicitly pass `exif_rotation=False`.

fix

If the raw, unrotated dimensions are needed, call `imagesize.get(filepath, exif_rotation=False)`.

affects: >=2.0.0

gotchaThe library primarily reads image *headers*. While it's generally robust, some severely corrupted images might still report dimensions if their headers are partially intact, even if the image data itself is unusable.

fix

Consider adding additional image integrity checks if your application requires highly reliable image data beyond just header parsing.

affects: All

gotchaFor SVG images, `imagesize` only supports pixel dimensions and `viewBox` attributes. Percentage values for dimensions are not supported.

fix

Ensure SVG assets are defined with explicit pixel dimensions or a `viewBox` for reliable parsing with `imagesize`.

affects: All

breakingThe `imagesize.get_info()` function has been removed in version 2.0. Code that relied on this function will raise an AttributeError. Users should migrate to `imagesize.get()` for dimensions and `imagesize.getDPI()` for DPI information.

fix

Update code that uses `imagesize.get_info()` to instead use `imagesize.get(filepath)` for dimensions or `imagesize.getDPI(filepath)` for DPI. The API has been refactored.

affects: >=2.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'imagesize'

The `imagesize` library has not been installed in the Python environment or the environment is not correctly activated.

fix

Install the library using pip: `pip install imagesize`

AttributeError: module 'imagesize' has no attribute 'get_imagesize'

Users are attempting to call an old function name (`get_imagesize`) that was deprecated in version 1.0.0 and removed in newer versions, instead of the current `imagesize.get`.

fix

Use the updated function name: `width, height = imagesize.get('image.jpg')`

FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_image.jpg'

The specified image file path does not exist or is incorrect, preventing `imagesize` from opening the file.

fix

Verify that the file path is correct and the file exists at that location, using an absolute path or ensuring the relative path is accurate.

imagesize.UnidentifiedImageError: cannot identify image file <path/to/image.file>

The provided file is either not a recognized image format, is corrupted, or its header information is malformed in a way that `imagesize` cannot parse.

fix

Ensure the file is a valid, supported image format (e.g., JPEG, PNG, GIF) and not corrupted. If the file is expected to be valid, verify its integrity or try opening it with an image viewer.

Upgrade

Version history

2.0.1latest on PyPI · released Aug 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/shibukawa/imagesize_py ↗

packagehttps://pypi.org/project/imagesize/ ↗