netpbmfile¶

Read and write Netpbm files.

Netpbmfile is a Python library to read and write image files in the Netpbm or related formats:

PBM (Portable Bit Map): P1 (text) and P4 (binary)
PGM (Portable Gray Map): P2 (text) and P5 (binary)
PPM (Portable Pixel Map): P3 (text) and P6 (binary)
PNM (Portable Any Map): shorthand for PBM, PGM, and PPM collectively
PAM (Portable Arbitrary Map): P7, bilevel, gray, rgb, and arbitrary depths
PGX (Portable Graymap Signed): PG, signed grayscale
PFM (Portable Float Map): Pf (gray), PF (rgb), and PF4 (rgba), read-only
XV thumbnail: P7 332 (rgb332), read-only

The Netpbm formats are specified at https://netpbm.sourceforge.net/doc/.

The PGX format is specified in ITU-T Rec. T.803.

No gamma correction or scaling is performed.

Author:: Christoph Gohlke
License:: BSD-3-Clause
Version:: 2026.1.29
DOI:: 10.5281/zenodo.17903402

Quickstart¶

Install the netpbmfile package and all dependencies from the Python Package Index:

python -m pip install -U "netpbmfile[all]"

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements¶

This revision was tested with the following requirements and dependencies (other versions may work):

CPython 3.11.9, 3.12.10, 3.13.11, 3.14.2 64-bit
NumPy 2.4.1

Revisions¶

2026.1.29

Fix code review issues.

2026.1.8

Improve code quality.

2025.12.12

Drop support for Python 3.10, support Python 3.14.

2025.5.8

Remove doctest command line option.

2025.1.1

Improve type hints.
Drop support for Python 3.9, support Python 3.13.

2024.5.24

…

Refer to the CHANGES file for older revisions.

Examples¶

Write a numpy array to a Netpbm file in grayscale binary format:

>>> import numpy
>>> data = numpy.array([[0, 1], [65534, 65535]], dtype=numpy.uint16)
>>> imwrite('_tmp.pgm', data)

Read the image data from a Netpbm file as numpy array:

>>> image = imread('_tmp.pgm')
>>> numpy.testing.assert_equal(image, data)

Access meta and image data in a Netpbm file:

>>> with NetpbmFile('_tmp.pgm') as pgm:
...     pgm.magicnumber
...     pgm.axes
...     pgm.shape
...     pgm.dtype
...     pgm.maxval
...     pgm.asarray().tolist()
...
'P5'
'YX'
(2, 2)
dtype('>u2')
65535
[[0, 1], [65534, 65535]]

View the image and metadata in the Netpbm file from the command line:

$ python -m netpbmfile _tmp.pgm

License¶

Copyright (c) 2011-2026, Christoph Gohlke
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

netpbmfile module¶

netpbmfile.__version__ = '2026.1.29'¶: Netpbmfile version string.

class netpbmfile.NetpbmFile(file, /, *, byteorder=None)¶

Bases: object

Read and write Netpbm and related files.

Parameters:

file (str | os.PathLike[Any] | BinaryIO | None) – Name of file or open binary file to read. None creates an empty instance.
byteorder (ByteOrder | None) – Byte order of image data in file. By default, all formats are big-endian except for PFM, which encodes the byte order in the file header.

__init__(file, /, *, byteorder=None)¶

Parameters:

file (str | os.PathLike[Any] | BinaryIO | None)
byteorder (ByteOrder | None)

Return type:

None

header: str¶: Netpbm header starting with magicnumber.

magicnumber: MagicNumber¶: ID determining Netpbm type.

width: int¶: Number of columns in image.

height: int¶: Number of rows in image.

depth: int¶: Number of samples per pixel.

maxval: int¶: Maximum value of image samples.

scale: float¶: Factor to scale image values in PFM formats, else zero.

__weakref__¶: list of weak references to the object

tupltype: str¶: Kind of PAM image.

dataoffset: int¶: Position of image data in file.

filename: str¶: File name.

byteorder: ByteOrder¶: Byte order of binary image data.

dtype: numpy.dtype[Any]¶: Data type of image array.

frames: int¶: Number of frames in image.

classmethod fromdata(data, /, *, magicnumber=None, maxval=None, tupltype=None)¶

Initialize instance from numpy array.

Parameters:

data (ArrayLike) – Image data.
magicnumber (MagicNumber | None) – ID determining Netpbm type. By default, this is determined from the data shape, dtype, and maxval.
maxval (int | None) – Maximum value of image samples. By default, this is determined from the data.
tupltype (str | None) – Kind of PAM image. By default, this is determined from the magicnumber and data shape and dtype.

Return type:

NetpbmFile

asarray(*, copy=True, cache=False)¶

Return image array.

Parameters:

copy (bool) – Return a copy of image array.
cache (bool) – Keep a copy of image data after reading from file.

Return type:

NDArray[Any]

write(file, /, *, magicnumber=None, byteorder=None, comment=None)¶

Write instance to file.

Parameters:

file (str | os.PathLike[Any] | BinaryIO) – Name of file or open binary file to write.
magicnumber (MagicNumber | None) – Netpbm format to write. By default, the instance’s magicnumber is used. PFM and XV formats are not supported.
byteorder (ByteOrder | None) – Byte order for 16-bit image data in P5 and P6 formats. By default, the byte order is ‘>’. Other formats are written in the byte order of the data array.
comment (str | None) – Single line ASCII string to write to PNM and PAM formats. Maximum 66 characters.

Return type:

None

close()¶

Close open file.

Return type:: None

property shape: tuple[int, ...]¶: Shape of image array.

property axes: str¶: Axes of image array.

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

netpbmfile.imread(file, /, *, byteorder=None)¶

Return image data from Netpbm file.

Parameters:

file (str | os.PathLike[Any] | BinaryIO) – Name of file or open binary file to read.
byteorder (ByteOrder | None) – Byte order of image data in file. By default, all formats are big-endian except for PFM, which encodes the byte order in the file header.

Return type:

NDArray[Any]

netpbmfile.imsave(file, data, /, *, magicnumber=None, maxval=None, tupltype=None, byteorder=None, comment=None)¶

Write image data to Netpbm file.

Parameters:

file (str | os.PathLike[Any] | BinaryIO) – Name of file or open binary file to write.
data (ArrayLike) – Image data to write.
magicnumber (MagicNumber | None) – Netpbm format to write. By default, this is determined from the data shape, dtype, and maxval. Writing PFM and XV formats is not supported.
maxval (int | None) – Maximum value of image samples. By default, this is determined from the data.
tupltype (str | None) – Kind of PAM image. By default, this is determined from the magicnumber and data shape and dtype.
byteorder (ByteOrder | None) – Byte order for 16-bit image data in P5 and P6 formats. By default, the byte order is ‘>’. Other formats are written in the byte order of the data array.
comment (str | None) – Single line ASCII string to write to PNM and PAM formats. Maximum 66 characters.

Return type:

None

netpbmfile.imwrite(file, data, /, *, magicnumber=None, maxval=None, tupltype=None, byteorder=None, comment=None)¶

Write image data to Netpbm file.

Parameters:

file (str | os.PathLike[Any] | BinaryIO) – Name of file or open binary file to write.
data (ArrayLike) – Image data to write.
magicnumber (MagicNumber | None) – Netpbm format to write. By default, this is determined from the data shape, dtype, and maxval. Writing PFM and XV formats is not supported.
maxval (int | None) – Maximum value of image samples. By default, this is determined from the data.
tupltype (str | None) – Kind of PAM image. By default, this is determined from the magicnumber and data shape and dtype.
byteorder (ByteOrder | None) – Byte order for 16-bit image data in P5 and P6 formats. By default, the byte order is ‘>’. Other formats are written in the byte order of the data array.
comment (str | None) – Single line ASCII string to write to PNM and PAM formats. Maximum 66 characters.

Return type:

None

netpbmfile¶

Quickstart¶

Requirements¶

Revisions¶

Examples¶

License¶

netpbmfile module¶

Documentation

Table of Contents

Related Topics