Version

Quick search

Table Of Contents

Image

The Image widget is used to display an image:

Example in python:

wimg = Image(source='mylogo.png')

Kv Example:

Image:
    source: 'mylogo.png'
    size: self.texture_size

Asynchronous Loading

To load an image asynchronously (for example from an external webserver), use the AsyncImage subclass:

aimg = AsyncImage(source='http://mywebsite.com/logo.png')

This can be useful as it prevents your application from waiting until the image is loaded. If you want to display large images or retrieve them from URL’s, using AsyncImage will allow these resources to be retrieved on a background thread without blocking your application.

Alignment

By default, the image is centered inside the widget bounding box.

Adjustment

To control how the image should be adjusted to fit inside the widget box, you should use the fit_mode property. Available options include:

  • "scale-down": maintains aspect ratio without stretching.

  • "fill": stretches to fill widget, may cause distortion.

  • "contain": maintains aspect ratio and resizes to fit inside widget.

  • "cover": maintains aspect ratio and stretches to fill widget, may clip

image.

For more details, refer to the fit_mode.

You can also inherit from Image and create your own style. For example, if you want your image to be greater than the size of your widget, you could do:

class FullImage(Image):
    pass

And in your kivy language file:

<-FullImage>:
    canvas:
        Color:
            rgb: (1, 1, 1)
        Rectangle:
            texture: self.texture
            size: self.width + 20, self.height + 20
            pos: self.x - 10, self.y - 10

SVG Images

New in version 3.0.0.

SVG files are supported via the ThorVG image provider (img_thorvg_svg), which uses Kivy’s internal kivy.lib.thorvg binding. This binding is compiled into Kivy and ships with the official Kivy wheels, so .svg files are loaded automatically with no extra install step:

Image(source='icons/house.svg')

Because SVG is a vector format with no fixed pixel size, the provider rasterizes the file to a bitmap. The rasterization size is determined by:

  1. An explicit size parameter in the @image_provider: URI (see below).

  2. The SVG’s own declared width/height, subject to a configured minimum.

  3. The [svg] default_size config key (default 512), used when the SVG has no declared size or when the declared size is smaller.

To change the global minimum raster size:

from kivy.config import Config
Config.set('svg', 'default_size', '256')  # must be set before first load

Explicit raster size via URI

To rasterize an SVG at a specific size (overriding the config default), use the @image_provider: URI with a size parameter:

# Rasterize at 128 pixels (aspect ratio preserved)
Image(source='@image_provider:thorvg_svg[size=128](icons/house.svg)')

This is useful when you know the maximum display size and want to avoid rasterizing at the full 512-pixel default for small icons.

class kivy.uix.image.AsyncImage(**kwargs)

Bases: kivy.uix.image.Image

Asynchronous Image class. See the module documentation for more information.

Note

The AsyncImage is a specialized form of the Image class. You may want to refer to the loader documentation and in particular, the ProxyImage for more detail on how to handle events around asynchronous image loading.

Note

AsyncImage currently does not support properties anim_loop and mipmap and setting those properties will have no effect.

remove_from_cache()

Remove image from cache.

New in version 2.0.0.

class kivy.uix.image.Image(**kwargs)

Bases: kivy.uix.widget.Widget

Image class, see module documentation for more information.

reload()

Reload image from disk. This facilitates re-loading of images from disk in case the image content changes.

New in version 1.3.0.

Usage:

im = Image(source = '1.jpg')
# -- do something --
im.reload()
# image will be re-loaded from disk
remove_from_cache()

Remove image from cache.

New in version 2.0.0.

« Grid Layout Label »