Pygame-ce Home || Help Contents

|| Reference Index

Most useful stuff: Color | display | draw | event | font | image |

key | locals | mixer | mouse | Rect | Surface | time | music |
pygame
pygame-ce documentation Advanced stuff: cursors | joystick | mask | sprite | transform |
BufferProxy | freetype | gfxdraw | midi | PixelArray | pixelcopy |
sndarray | surfarray | math
Other: camera | controller | examples | scrap | system | tests |
touch | typing | version | Window

pygame.image
pygame module for image transfer

pygame.image.load
load new image from a file (or file-like object)

pygame.image.load_sized_svg
load an SVG image from a file (or file-like object) with the given size

pygame.image.save
save an image to file (or file-like object)

pygame.image.get_sdl_image_version
get version number of the SDL_Image library being used

pygame.image.get_extended
test if extended image formats can be loaded

pygame.image.tostring
transfer image to byte buffer

pygame.image.tobytes
transfer image to byte buffer

pygame.image.fromstring
create new Surface from a byte buffer

pygame.image.frombytes
create new Surface from a byte buffer

pygame.image.frombuffer
create a new Surface that shares data inside a bytes buffer
 pygame.image.load_basic
load new BMP image from a file (or file-like object)

pygame.image.load_extended
load an image from a file (or file-like object)

pygame.image.save_extended
save a png/jpg image to file (or file-like object)

The image module contains functions for loading and saving pictures, as well as transferring
Surfaces to formats usable by other packages.
Note that there is no Image class; an image is loaded as a Surface object. The Surface class
allows manipulation (drawing lines, setting pixels, capturing regions, etc.).
In the vast majority of installations, pygame is built to support extended formats, using the
SDL_Image library behind the scenes. However, some installations may only support uncom-
pressed BMP images. With full image support, the pygame.image.load() function can load
the following formats.
BMP
GIF (non-animated)
JPEG
LBM
PCX
PNG
PNM ( PBM , PGM , PPM )
QOI
SVG (limited support, using Nano SVG)
TGA (uncompressed)
TIFF
WEBP
XPM
XCF

New in pygame 2.0: Loading SVG, WebP, PNM

New in pygame-ce 2.4.0: Loading QOI (Relies on SDL_Image 2.6.0+)
Saving images only supports a limited set of formats. You can save to the following formats.
BMP
JPEG
PNG
TGA

JPEG and JPG , as well as TIF and TIFF refer to the same file format
New in pygame 1.8: Saving PNG and JPEG files.

pygame.image.load()
load new image from a file (or file-like object)
load(file) -> Surface
load(file, namehint="") -> Surface
 Load an image from a file source. You can pass either a filename, a Python file-like object,
or a pathlib.Path.
Pygame will automatically determine the image type (e.g., GIF or bitmap) and create a
new Surface object from the data. In some cases it will need to know the file extension
(e.g., GIF images should end in ".gif"). If you pass a raw file-like object, you may also
want to pass the original filename as the namehint argument.
The returned Surface will contain the same color format, colorkey and alpha transparency
as the file it came from. You will often want to call pygame.Surface.convert() with no
arguments, to create a copy that will draw more quickly on the screen.
For alpha transparency, like in .png images, use the pygame.Surface.convert_alpha()
method after loading so that the image has per pixel transparency.
Pygame may not always be built to support all image formats. At minimum it will support
uncompressed BMP . If pygame.image.get_extended() returns True , you should be
able to load most images (including PNG, JPG and GIF).
You should use os.path.join() for compatibility.

eg. asurf = pygame.image.load(os.path.join('data', 'bla.png'))

Changed in pygame-ce 2.2.0: Now supports keyword arguments.

pygame.image.load_sized_svg()
load an SVG image from a file (or file-like object) with the given size
load_sized_svg(file, size) -> Surface

This function rasterizes the input SVG at the size specified by the size argument. The
file argument can be either a filename, a Python file-like object, or a pathlib.Path.
The usage of this function for handling SVGs is recommended, as calling the regular load
function and then scaling the returned surface would not preserve the quality that an SVG
can provide.
It is to be noted that this function does not return a surface whose dimensions exactly
match the size argument. This function preserves aspect ratio, so the returned surface
could be smaller along at most one dimension.
This function requires SDL_image 2.6.0 or above. If pygame was compiled with an older
version, pygame.error will be raised when this function is called.
New in pygame-ce 2.4.0.

pygame.image.save()
save an image to file (or file-like object)
save(Surface, file) -> None
save(Surface, file, namehint="") -> None

This will save your Surface as either a BMP , TGA , PNG , or JPEG image. If the filename
extension is unrecognized it will default to TGA . Both TGA , and BMP file formats create un-
compressed files. You can pass a filename, a pathlib.Path or a Python file-like object. For
 file-like object, the image is saved to TGA format unless a namehint with a recognizable
extension is passed in.

Note: When saving to a file-like object, it seems that for most formats, the object needs
to be flushed after saving to it to make loading from it possible.

Changed in pygame 1.8: Saving PNG and JPEG files.

Changed in pygame 2.0.0: The namehint parameter was added to make it possible to
save other formats than TGA to a file-like object. Saving to a file-like object with JPEG is
possible.
Changed in pygame-ce 2.2.0: Now supports keyword arguments.

pygame.image.get_sdl_image_version()
get version number of the SDL_Image library being used
get_sdl_image_version(linked=True) -> None
get_sdl_image_version(linked=True) -> (major, minor, patch)

If pygame is built with extended image formats, then this function will return the
SDL_Image library's version number as a tuple of 3 integers (major, minor, patch) . If
not, then it will return None .
linked=True is the default behavior and the function will return the version of the library
that Pygame is linked against, while linked=False will return the version of the library
that Pygame is compiled against.
New in pygame 2.0.0.
Changed in pygame-ce 2.1.4: linked keyword argument added and default behavior
changed from returning compiled version to returning linked version

pygame.image.get_extended()
test if extended image formats can be loaded
get_extended() -> bool

If pygame is built with extended image formats this function will return True. It is still not
possible to determine which formats will be available, but generally you will be able to load
them all.

pygame.image.tostring()
transfer image to byte buffer
tostring(Surface, format, flipped=False, pitch=-1) -> bytes

DEPRECATED: This function has the same functionality as tobytes() , which is pre-
ferred and should be used.
Deprecated since pygame-ce 2.3.0.

pygame.image.tobytes()
 transfer image to byte buffer
tobytes(Surface, format, flipped=False, pitch=-1) -> bytes

Creates a string of bytes that can be transferred with the fromstring or frombytes
methods in other Python imaging packages. Some Python image packages prefer their im-
ages in bottom-to-top format (PyOpenGL for example). If you pass True for the flipped ar-
gument, the byte buffer will be vertically flipped.
The format argument is a string of one of the following values. Note that only 8-bit
Surfaces can use the "P" format. The other formats will work for any Surface. Also note
that other Python image packages support more formats than pygame.
P , 8-bit palettized Surfaces
RGB , 24-bit image
RGBX , 32-bit image with unused space
RGBA , 32-bit image with an alpha channel
ARGB , 32-bit image with alpha channel first
BGRA , 32-bit image with alpha channel, red and blue channels swapped
ABGR , 32-bit image with alpha channel, reverse order
RGBA_PREMULT , 32-bit image with colors scaled by alpha channel
ARGB_PREMULT , 32-bit image with colors scaled by alpha channel, alpha channel first

The 'pitch' argument can be used to specify the pitch/stride per horizontal line of the image
in bytes. It must be equal to or greater than how many bytes the pixel data of each hori-
zontal line in the image bytes occupies without any extra padding. By default, it is -1 ,
which means that the pitch/stride is the same size as how many bytes the pure pixel data
of each horizontal line takes.

Note: The use of this function is recommended over tostring() as of pygame 2.1.3.
This function was introduced so it matches nicely with other libraries (PIL, NumPy, etc),
and with people's expectations.

New in pygame-ce 2.1.3.

Changed in pygame-ce 2.2.0: Now supports keyword arguments.
Changed in pygame-ce 2.5.0: Added a 'pitch' argument.
Changed in pygame-ce 2.5.1: Added support for ABGR image format

pygame.image.fromstring()
create new Surface from a byte buffer
fromstring(bytes, size, format, flipped=False, pitch=-1) -> Surface

DEPRECATED: This function has the same functionality as frombytes() , which is pre-
ferred and should be used.
Deprecated since pygame-ce 2.3.0.

pygame.image.frombytes()
create new Surface from a byte buffer
frombytes(bytes, size, format, flipped=False, pitch=-1) -> Surface
 This function takes arguments similar to pygame.image.tobytes() . The size argument
is a pair of numbers representing the width and height. Once the new Surface is created it
is independent from the memory of the bytes passed in.
The bytes and format passed must compute to the exact size of image specified.
Otherwise a ValueError will be raised.
The 'pitch' argument can be used specify the pitch/stride per horizontal line of the image
bytes in bytes. It must be equal to or greater than how many bytes the pixel data of each
horizontal line in the image bytes occupies without any extra padding. By default, it is -1 ,
which means that the pitch/stride is the same size as how many bytes the pure pixel data
of each horizontal line takes.
See the pygame.image.frombuffer() method for a potentially faster way to transfer im-
ages into pygame.

Note: The use of this function is recommended over fromstring() as of pygame

2.1.3. This function was introduced so it matches nicely with other libraries (PIL, NumPy,
etc), and with people's expectations.

New in pygame-ce 2.1.3.

New in pygame-ce 2.1.4: Added a 'pitch' argument and support for keyword arguments.

pygame.image.frombuffer()
create a new Surface that shares data inside a bytes buffer
frombuffer(buffer, size, format, pitch=-1) -> Surface

Create a new Surface that shares pixel data directly from a buffer. This buffer can be
bytes, a bytearray, a memoryview, a pygame.BufferProxy , or any object that supports
the buffer protocol. This method takes similar arguments to
pygame.image.fromstring() , but is unable to vertically flip the source data.
This will run much faster than pygame.image.fromstring() , since no pixel data must be
allocated and copied.
It accepts the following 'format' arguments:
P , 8-bit palettized Surfaces
RGB , 24-bit image
BGR , 24-bit image, red and blue channels swapped.
RGBX , 32-bit image with unused space
RGBA , 32-bit image with an alpha channel
ARGB , 32-bit image with alpha channel first
BGRA , 32-bit image with alpha channel, red and blue channels swapped

The 'pitch' argument can be used specify the pitch/stride per horizontal line of the image
buffer in bytes. It must be equal to or greater than how many bytes the pixel data of each
horizontal line in the image buffer occupies without any extra padding. By default, it is -1 ,
which means that the pitch/stride is the same size as how many bytes the pure pixel data
of each horizontal line takes.
New in pygame-ce 2.1.3: BGRA format
 New in pygame-ce 2.1.4: Added a 'pitch' argument and support for keyword arguments.

pygame.image.load_basic()
load new BMP image from a file (or file-like object)
load_basic(file, /) -> Surface

Load an image from a file source. You can pass either a filename or a Python file-like ob-
ject, or a pathlib.Path.
This function only supports loading "basic" image format, ie BMP format. This function is
always available, no matter how pygame was built.

pygame.image.load_extended()
load an image from a file (or file-like object)
load_extended(file) -> Surface
load_extended(file, namehint="") -> Surface

This function is similar to pygame.image.load() , except that this function can only be
used if pygame was built with extended image format support.
Changed in pygame 2.0.1: This function is always available, but raises an
NotImplementedError if extended image formats are not supported. Previously, this
function may or may not be available, depending on the state of extended image format
support.
Changed in pygame-ce 2.2.0: Now supports keyword arguments.

pygame.image.save_extended()
save a png/jpg image to file (or file-like object)
save_extended(Surface, file) -> None
save_extended(Surface, file, namehint="") -> None

This will save your Surface as either a PNG or JPEG image.

In case the image is being saved to a file-like object, this function uses the namehint argu-
ment to determine the format of the file being saved. Saves to JPEG in case the namehint
was not specified while saving to a file-like object.
Changed in pygame 2.0.1: This function is always available, but raises an
NotImplementedError if extended image formats are not supported. Previously, this
function may or may not be available, depending on the state of extended image format
support.
Changed in pygame-ce 2.2.0: Now supports keyword arguments.

Edit on GitHub