Install & Compatibility
Where this runs
tested against v0.20220715.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.002s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
png
✓ import png
✗ import pypng
The PyPI package name is `pypng`, but the module is imported as `png`.
This quickstart demonstrates how to create a simple grayscale PNG image from a Python list of lists representing pixel data. It uses the `png.from_array` function for convenience and saves the image to a file.
import png
import os
# Create a simple 2x2 grayscale image (Luminance) with a bit depth of 8
rows = [
[255, 0], # White, Black
[0, 255] # Black, White
]
# Create an image from a 2D array and save it
image_file_path = 'simple_image.png'
png.from_array(rows, 'L').save(image_file_path)
print(f"Image saved to {image_file_path}")
# Clean up the created file
# os.remove(image_file_path)
Debug
Known issues
breakingThe `lenient` flag has been removed. PNG chunk checksum errors are now treated as warnings instead of exceptions and can be managed using Python's standard `warnings` module.fixRemove the `lenient` flag from your `Reader` initialization. Handle checksum warnings via Python's `warnings` module if needed.
affects: 0.20231004.0 and later
breakingThe `interlace` keyword argument has been removed from the `Writer` class, and interlaced output is no longer supported.fixRemove the `interlace` argument from `png.Writer` calls. If interlaced output is strictly required, an older version of `pypng` or an alternative library must be used.
affects: 0.20250521.0 and later
breakingPassing an empty file to PyPNG now raises a built-in `EOFError` instead of `png.FormatError`. This change helps distinguish empty file issues from genuine format errors.fixUpdate exception handling to catch `EOFError` for empty file scenarios, while still catching `png.FormatError` for other invalid PNG format issues.
affects: 0.20220715.0 and later
gotchaFiles for reading or writing PNGs must always be opened in binary mode (e.g., `'wb'` for writing, `'rb'` for reading) to prevent data corruption or unexpected errors.fixEnsure file opening statements explicitly include the binary mode flag (e.g., `with open('image.png', 'wb') as f:`). affects: All versions
gotchaIncorrect bit depth specification or pixel data formatting can lead to corrupted images. Pixel data must match the `Writer` configuration (e.g., grayscale, RGB, RGBA) and the declared bit depth.fixCarefully align the pixel data structure and values with the `bitdepth`, `greyscale`, and `alpha` parameters when initializing `png.Writer` or using `png.from_array`'s mode argument. For example, 'L;16' for 16-bit grayscale.
affects: All versions
gotchaWhen calculating image dimensions, especially for `width` from row data (e.g., `len(row) / channels_per_pixel`), ensure you use integer division (`//`) instead of float division (`/`). Using float division where an integer is expected can lead to `TypeError`.fixReplace `/` with `//` for calculations that are expected to result in an integer, such as `width = len(row) // 3` for an RGB image.
affects: All versions
Upgrade
Version history
0.20220715.0latest on PyPI · released Jul 15, 2022
Audit
Dependencies
No dependency data recorded yet.