Pure Python implementation of the GIMP image formats (.xcf projects as well as brushes, patterns, etc)

Forked from

A pure python implementation of the GIMP XCF image format. Use this to interact
with GIMP image formats

Issues and contributions very much wanted/ needed :smile:

Previously under gimpformats_unofficial now under gimpformats

Getting started

Read an image

from gimpformats.gimpXcfDocument import GimpDocument
project = GimpDocument("image.xcf")

Iterate the image and report the contents of each group followed by the first
level children of the image

"""List data on groups followed by the direct children of a gimp xcf document
layers = project.layers
index = 0
print("## Group info...")
while index < len(layers):
	layerOrGroup = layers[index]
	if layerOrGroup.isGroup:
		index += 1
		while layers[index].itemPath is not None:
			print("Group \"" + + "\" contains Layer \"" + layers[index].name + "\"")
		index += 1

print("## Document direct children...")
for layerOrGroup in layers:
	print("\"" + + "\" is a " + ("Group" if layerOrGroup.isGroup else "Layer"))

Example output:

## Group info...
Group "Layer Group" contains Layer "Layer"
Group "Layer Group" contains Layer "Layer2"
## Document direct children...
"bg #1" is a Layer
"bg" is a Layer
"bg #2" is a Layer
"Transformation" is a Layer
"Layer Group" is a Group
"Background" is a Layer

Next tasks (see below)

  • Saving

Currently supports

  • Loading xcf files (up to current GIMP version 2.10)
  • Getting image hierarchy and info
  • Getting image for each layer (PIL image)
  • .gbr brushes
  • .vbr brushes
  • .gpl palette files
  • .pat pattern files
  • .gtp tool presets
  • Generate a flattened image
  • Add new layers

In progress but results in crashes and tests failing

  • Saving
  • .ggr gradients - reads/saves fine, but I need to come up with a way to get the
    actual colours
  • .gih brush sets - BUG: seems to have more image data per brush than what's
  • .gpb brush - should work, but I need some test files

Not implemented

  • Exported paths in .svg format. - Reading should be easy enough, but I need to
    ensure I don't get a full-blown svg in the mix
  • Standard "parasites"


See the Docs for more information.

Install With PIP

pip install gimpformats

Head to for more info

Language information

Built for

This program has been written for Python 3 and has been tested with
Python version 3.9.0

Install Python on Windows


choco install python


To install Python, go to and download the latest

Install Python on Linux


sudo apt install python3.9

How to run

With VSCode

  1. Open the .py file in vscode
  2. Ensure a python 3.9 interpreter is selected (Ctrl+Shift+P > Python:Select
    Interpreter > Python 3.9)
  3. Run by pressing Ctrl+F5 (if you are prompted to install any modules, accept)

From the Terminal


Download Project


Using The Command Line

  1. Press the Clone or download button in the top right
  2. Copy the URL (link)
  3. Open the command line and change directory to where you wish to
    clone to
  4. Type 'git clone' followed by URL in step 2
$ git clone

More information can be found at

Using GitHub Desktop

  1. Press the Clone or download button in the top right
  2. Click open in desktop
  3. Choose the path for where you want and click Clone

More information can be found at

Download Zip File

  1. Download this GitHub repository
  2. Extract the zip archive
  3. Copy/ move to the desired location