Skip to content

Images

Image loads and decodes images with the platform's native image loader. Each platform caches responses and cancels obsolete requests when a source changes or a component unmounts. Python doesn't download or decode image bytes.

Sources can be a bundled Asset, an https URL, a file path, or a data: URI. default_source shows a local image while a remote one loads (and keeps it if the load fails); blur_radius blurs the decoded bitmap. Supply layout constraints when an image must reserve space before its content loads.

pn.Image(
    source="https://example.com/photo.jpg",
    default_source=pn.asset("images/placeholder.png"),
    blur_radius=4,
    style=pn.style(width=200, height=120),
)

Images module

Images measures, prefetches, and clears the cache of the same pipeline:

size = await pn.Images.get_size(pn.asset("images/hero.png"))
await pn.Images.prefetch("https://example.com/photo.jpg")
pn.Images.clear_cache()

Image utilities backed by the native image pipeline.

Images exposes the parts of the platform image loader that don't fit on the Image element: measuring an image before laying it out, warming the cache, and clearing it. Every method takes the same source values Image does (a bundled Asset, a URL, a data: URI, or a file path) and runs off the main thread natively.

Example 
import pythonnative as pn

size = await pn.Images.get_size(pn.asset("images/hero.jpg"))
await pn.Images.prefetch("https://example.com/banner.png")

Off device (tests, pn preview) sizes are read from the file headers of PNG, JPEG, GIF, WebP, and BMP files, and prefetch is a no-op that reports whether the source is reachable.

Classes:

Name Description
ImageSize

Logical dimensions of an image, in points.
Images

Measure, prefetch, and clear images through the native loader.

ImageSize dataclass 

ImageSize(width: float, height: float)

Logical dimensions of an image, in points.

Attributes:

Name Type Description
width float

Width in logical points (pixels divided by the asset's scale).
height float

Height in logical points.

Images

Measure, prefetch, and clear images through the native loader.

Raises:

Type Description
NativeModuleError

If the native module reports a failure (for instance an unreachable URL or a missing asset).

Methods:

Name Description
get_size

Return the logical size of source without displaying it.
prefetch

Download and cache source ahead of time; True on success.
clear_cache

Drop the in-memory and on-disk image caches.

get_size async staticmethod 

get_size(source: Union[str, Asset]) -> ImageSize

Return the logical size of source without displaying it.

Bundled assets report the size of their 1x variant (the variant's pixel size divided by its scale), so the result is the size the image would take in layout.

prefetch async staticmethod 

prefetch(source: Union[str, Asset]) -> bool

Download and cache source ahead of time; True on success.

clear_cache staticmethod 

clear_cache() -> None

Drop the in-memory and on-disk image caches.

Next steps