krita4python 0.1.2.post20260512

Pure-Python reader and writer for Krita (.kra) files. No Krita install required.

krita4python

Pure-Python reader and writer for Krita's native .kra files. No Krita install required, no C extension required, and it runs on every Python that Pillow supports (3.9 – 3.13+).

kritapy/kra-py on PyPI is write-only and breaks on Python 3.12+; krita4python is a clean-room reimplementation against the documented format so it stays working.

Install

pip install krita4python

Optional speedups (NumPy for the planar/interleaved conversion, python-lzf for the C LZF codec):

pip install "krita4python[speed]"

Everything still works without them, it's just slower on big layers.

Read a .kra

from krita4python import read_kra

doc = read_kra("character.kra")
print(doc.width, doc.height)
for layer in doc.iter_paint_layers():
    print(layer.name, layer.x, layer.y, layer.opacity, layer.visible)
    if layer.image is not None:
        layer.image.save(f"{layer.name}.png")

doc.layers is a tree of KraGroup/KraLayer nodes in back-to-front order. layer.image is a Pillow RGBA image sized to the layer's tight bounding box; layer.x/y is its canvas offset.

Write a .kra

from PIL import Image
from krita4python import write_kra, KraDocument, KraLayer

doc = KraDocument(
    width=1024, height=1024,
    layers=[
        KraLayer(name="bg", image=Image.open("bg.png")),
        KraLayer(name="char", image=Image.open("char.png"), x=128, y=64),
    ],
)
write_kra("out.kra", doc)

The resulting file opens in Krita 5.x and round-trips back through read_kra.

CLI

krita4python extract character.kra -o ./layers/
krita4python pack ./layers/ -o repacked.kra

What's supported

• RGBA / 8-bit paint layers (the format used by 99%+ of .kra files).
• Group layers, nesting, visibility, opacity, composite-op, layer offsets.
• mergedimage.png and preview.png (auto-generated on write).
• Tile-level LZF compression with the documented planar BGRA layout.

What's NOT supported (yet)

• Non-8-bit color depths (16f / 32f).
• Non-RGBA colorspaces (CMYK, grayscale).
• Filter, vector, transform-mask, file-reference, clone layers (we surface their metadata but not pixels).
• Per-layer ICC profiles.

PRs welcome.

Why does this exist

OpenLive2D needed real .kra reading on Python 3.13 (where kritapy raises a dataclass error on import). Rather than depend on Krita running headlessly, krita4python reimplements the format. License is GPL-3.0.