Making Photoshop Layer Groups With ImageMagick

ImageMagick can create simple layered PSD files but cannot create layer groups in those PSD files.

At least, that is the conventional wisdom. The official answer from the ImageMagick maintainers is pretty direct: there is no mechanism for grouping images into a hierarchy. Fair enough. PSD is a complicated format and ImageMagick is an image-processing tool, not a Photoshop replacement.

One time, while trial-and-erroring the layered PSD functionality of ImageMagick, I created a PSD with a folder. (The name was ASCII gibberish and it was empty).

Obviously, this meant I had to stop whatever useful thing I was doing and spend an unreasonable amount of time trying to make it happen again, on purpose.

A Folder Is Not Really a Folder

The first useful discovery was that Photoshop layer groups are not represented as some elegant nested tree inside a PSD.

They are mostly a flat list of layers with specially marked records surrounding the layers that belong to the group.

Conceptually, it looks something like this:

My Folder
    Red Child
    Blue Child
</Layer group>

The folder-opening layer contains an additional-information block named lsct, short for layer section divider.

Adobe defines the relevant values as:

0 = normal layer
1 = open folder
2 = closed folder
3 = bounding section divider

The type-3 layer is the closing marker. Photoshop normally hides it from the Layers panel, which is why you do not see a bunch of literal </Layer group> layers while working normally.

That is more or less it. (Excluding, you know, the entire rest of the PSD format.)

Enter `psd:additional-info`

ImageMagick does not have anything in its api anything related to creating groups, but its PSD reader and writer do have a mechanism for retaining Photoshop metadata that ImageMagick itself does not understand.

When ImageMagick reads a PSD layer, it can preserve that layer’s extra binary records in a profile named:

psd:additional-info

When writing the PSD again with:

-define psd:additional-info=all

the PSD writer retrieves that profile and writes the bytes back into the layer’s additional-information area. The important part here is the word all. ImageMagick also has a selective mode, but lsct is not one of the blocks that selective mode retains.

So ImageMagick does not need to know what a Photoshop folder is, it just needs to be convinced to carry the folder bytes.

This is where things start getting questionable.

Building the Marker

An lsct block has an Image Resource Block-style header followed by the section-divider data.

The basic Python version looks like this:

import struct


def lsct_block(kind: int, blend_mode: bytes = b"pass") -> bytes:
    payload = (
        struct.pack(">I", kind)
        + b"8BIM"
        + blend_mode
    )

    return (
        b"8BIM"
        + b"lsct"
        + struct.pack(">I", len(payload))
        + payload
    )

For the opening folder layer:

folder_marker = lsct_block(1, b"pass")

And for the closing divider:

end_marker = lsct_block(3, b"norm")

pass is Photoshop’s pass-through blend mode, which is normally what a layer group uses.

Now we have the correct bytes.

We just need to attach them to a layer using the exact profile name psd:additional-info.

Simple, right?

Profiles, but Not Quite the Profile We Need

ImageMagick’s command line can attach a binary profile:

magick marker.png -profile folder-marker.bin marker.miff

Unfortunately, it identifies the data as a generic 8bim profile. That is not the name the PSD writer looks for.

The writer specifically asks for:

psd:additional-info

I could not find a clean command-line option for assigning arbitrary bytes under that exact profile name.

MIFF, ImageMagick’s own image format, turned out to be a useful way around this. MIFF stores profiles with a readable header followed by the binary profile data.

So the current hack is:

Create a transparent marker image.
Attach the lsct bytes as a normal profile.
Save it as MIFF.
Change the MIFF header from:
```
profile=8bim
```
to:
```
profile=psd:additional-info
```
Feed that MIFF back into ImageMagick.
Write the PSD using -define psd:additional-info=all.

Is editing a MIFF header to smuggle Photoshop metadata through ImageMagick elegant?

No.

Does it work?

Also no, at first.

But eventually, yes.

First Attempt: “Index”

The first generated PSD opened in Photoshop as one flattened layer named:

Index

Not exactly the beautiful folder hierarchy I was aiming for.

The tiny test images had been optimized into palette images. ImageMagick saw the images as indexed or pseudo-class data and wrote an indexed-color PSD rather than a normal RGB document.

Photoshop cannot preserve the intended layer setup in that form, so the document effectively collapsed.

The fix was to force the source files and final document into direct RGB with alpha:

PNG32:
-colorspace sRGB
-type TrueColorAlpha

That got me past just having one layer named "Index".

Second Attempt: Photoshop Notices Something

Once the file was a real RGB layered PSD, Photoshop started showing all the records separately:

</Layer group>
Blue Child
Red Child
My Folder

That was encouraging, but not actually correct.

Photoshop also displayed a warning that some layers were corrupted and had been restored. More interestingly, the closing marker appeared as a visible layer literally named:

</Layer group>

That layer is supposed to be hidden by Photoshop once it recognizes the record as a valid bounding section divider.

So this proved an important intermediate point:

Photoshop was not ignoring the metadata.
The lsct blocks were definitely being read.
The file structure still was not quite what Photoshop wanted.

In other words, I had crossed the line from “totally unsupported” into “Photoshop sees what you are trying to do and is mildly annoyed about it.”

Layer Order

The first near-success also came into Photoshop backwards.

I supplied the records in the intuitive order:

My Folder
Red Child
Blue Child
</Layer group>

Photoshop displayed them as:

</Layer group>
Blue Child
Red Child
My Folder

That turned out not to be a random oddity.

For the next version, I reversed the order fed to ImageMagick and also changed the closing divider from the shortest lsct=3 payload to the fuller section-divider form.

That version worked.

The Successful Version

The v3 test finally opened in Photoshop as a proper folder.

No visible stray </Layer group> layer.

No warning about corrupted layers being restored.

Just an actual group:

My Folder
    Red Child
    Blue Child

ImageMagick can be used to generate a PSD with a real Photoshop layer group, provided you inject the proper lsct additional-info records and structure the layer stack the way Photoshop expects.

This is still a hack. It is not a first-class feature. But it is not imaginary.

What Seems to Matter

At this point, the ingredients appear to be:

1. Force RGB, not indexed color

If ImageMagick writes an indexed PSD, the whole thing falls apart immediately. The document needs to stay in normal RGB and alpha territory.

2. Preserve metadata using `psd:additional-info`

This is the essential loophole. Without that passthrough, there is no place to stash the section-divider data.

3. Inject valid `lsct` blocks

The start marker needs the folder section-divider metadata, and the end marker needs the bounding-divider metadata.

4. Feed the layers in the order ImageMagick will serialize correctly

The logical order was not the right order for the final PSD. Reversing the layer-record input order was the final element needed to create a working, layered, psd.

Is This Actually Useful?

Surprisingly, yes.

Not because this is a clean, supported ImageMagick feature. It definitely is not.

But because it means there is a real path for generating structured PSDs with groups without needing Photoshop itself, as long as you are willing to do slightly cursed metadata work.

That could be useful in automation pipelines where:

ImageMagick is already available.
Layered PSD output is needed.
Some amount of PSD structure matters.
“Slightly deranged but reproducible” is an acceptable engineering category.

Final Thoughts

The official story is still basically true: ImageMagick does not support Photoshop layer groups as a native concept.

But that is not the same as saying it cannot produce them.

It can, through the side door.

The side door is:

psd:additional-info
raw lsct section-divider records
MIFF profile shenanigans
a slightly counterintuitive layer-ordering trick

So the updated claim is:

ImageMagick does not have folder support.
But it can be coerced into writing a PSD that Photoshop opens as a real layer group.