Graphical content of arbitrary size.

Availability (Key)









Images and Icons are not the same!

Toga draws a distinction between an Image and an Icon. An Image can have an arbitrary size or aspect ratio, and is not platform dependent - the same image will be used on every platform. An Image is not an interactive element, because there is no visual cue to the user that the image can be interacted with.

An Icon, on the other hand, is small, square, and might vary between platforms. It is a visual element that is often used as part of an interactive element such as a button, a toolbar item, or a tab selector - but the Icon itself isn’t an interactive element.

If you are looking for a widget that the user can click on, you’re looking for a widget configured to use an Icon (probably Button), not an on_press handler on an Image or ImageView.

An image can be constructed from a wide range of sources:

from pathlib import Path
import toga

# Load an image in the same folder as the file that declares the App class
my_image = toga.Image("brutus.png")

# Load an image at an absolute path
my_image = toga.Image(Path.home() / "path/to/brutus.png")

# Create an image from raw data
with (Path.home() / "path/to/brutus.png").open("rb") as f:
    my_image = toga.Image(

# Create an image from a PIL image (if PIL is installed)
import PIL.Image
my_pil_image ="L", (30, 30))
my_toga_image = toga.Image(my_pil_image)

You can also tell Toga how to convert from (and to) other classes that represent images via image format plugins.


  • PNG and JPEG formats are guaranteed to be supported. Other formats are available on some platforms:

    • GTK: BMP

    • macOS: GIF, BMP, TIFF

    • Windows: GIF, BMP, TIFF

  • The native platform representations for images are:

    • Android:

    • GTK: GdkPixbuf.Pixbuf

    • iOS: UIImage

    • macOS: NSImage

    • Windows: System.Drawing.Image

  • If you subclass Image, you can supply that subclass as the requested format to any as_format() method in Toga, provided that your subclass has a constructor signature compatible with the base Image class.


type ImageContentT

When specifying content for an Image, you can provide:

If a relative path is provided, it will be anchored relative to the module that defines your Toga application class.

class toga.Image(src=NOT_PROVIDED, *, path=NOT_PROVIDED, data=NOT_PROVIDED)

Create a new image.

  • src (ImageContentT) – The source from which to load the image. Can be any valid image content type.

  • path (object) – DEPRECATED - Use src.

  • data (object) – DEPRECATED - Use src.

  • FileNotFoundError – If a path is provided, but that path does not exist.

  • ValueError – If the source cannot be loaded as an image.


Return the image, converted to the image format specified.


format (type[ImageT]) – Format to provide. Defaults to Image; also supports PIL.Image.Image if Pillow is installed, as well as any image types defined by installed image format plugins.


The image in the requested format


TypeError – If the format supplied is not recognized.

Return type:


property data: bytes

The raw data for the image, in PNG format.

property height: int

The height of the image, in pixels.

property path: Path | None

The path from which the image was opened, if any (or None).


Save image to given path.

The file format of the saved image will be determined by the extension of the filename provided (e.g path/to/mypicture.png will save a PNG file).


path (str | Path) – Path to save the image to.

Return type:


property size: tuple[int, int]

The size of the image, as a (width, height) tuple.

property width: int

The width of the image, in pixels.