DEV Community: libersand

How to Read PSD Layers in Python with psd-tools

libersand — Sun, 25 Oct 2026 13:14:40 +0000

To read PSD layers in Python, install psd-tools, open the file with PSDImage.open(), and loop over psd.descendants(). Each layer gives you its name, kind, bbox, visible, opacity and blend_mode, and layer.composite() returns it as a Pillow image you can save as a transparent PNG.

This post walks through psd-tools on a real file and shows the output of every snippet. It also covers two things the official quick start doesn't mention. Smart object layers carry their own embedded file, which can be larger than what you see on the canvas. And by default psd.composite() hands back the merged image saved in the file instead of rendering the layers.

Everything below was run with psd-tools 1.26.0 (released 2026-10-21), Pillow 13.0.0 and Python 3.13 on macOS. The sample is a 3-layer, 880×1216 poster PSD exported by IntoLayers (more on that at the end), not by Photoshop. The scripts call it poster.psd.

Install psd-tools

psd-tools is an MIT-licensed Python package for reading and writing Adobe Photoshop PSD and PSB files. Version 1.26.0 needs Python 3.11 or newer and pulls in Pillow and NumPy:

pip install psd-tools
# optional: vector shapes, gradient and pattern fills, layer effects
pip install "psd-tools[composite]"

The psd-tools composite extra adds aggdraw and scipy. Everything in this post, smart object layers included, ran without it.

If a search sends you to psd-tools2 or psd-tools3, skip them. They are old forks: psd-tools3 last shipped 1.9.2 in February 2022, while the original psd-tools project on GitHub shipped 1.26.0 this month. The import name is psd_tools with an underscore.

Open a PSD and list every layer

PSDImage.open() reads the file, and descendants() walks every layer, including the ones inside groups. Plain iteration (for layer in psd) only gives you the top level, which is what the official README example and the older Stack Overflow answers use.

from psd_tools import PSDImage

psd = PSDImage.open("poster.psd")
print(psd.size, psd.color_mode.name, f"{psd.depth}-bit")

for layer in psd.descendants():
    print(f"{layer.kind:<11} {layer.name!r:<38} bbox={layer.bbox} "
          f"visible={layer.visible} opacity={layer.opacity} "
          f"blend={layer.blend_mode.name}")

Output:

(880, 1216) RGB 8-bit
pixel       'Background'                           bbox=(0, 0, 880, 1216) visible=True opacity=255 blend=NORMAL
smartobject 'Monstera potted plant illustration'   bbox=(110, 474, 734, 1139) visible=True opacity=255 blend=NORMAL
smartobject 'Poster text and badge elements'       bbox=(123, 0, 879, 422) visible=True opacity=255 blend=NORMAL

Output of list_layers.py on the sample PSD (psd-tools 1.26.0).

What each field means:

kind is the layer type as a short string: pixel, group, type, shape, smartobject and so on (full list below).
bbox is (left, top, right, bottom) in canvas pixels. layer.offset gives (left, top) and layer.size gives width and height.
opacity runs from 0 to 255, not 0 to 100. 255 is the "100%" you see in Photoshop.
blend_mode is a BlendMode enum. Use .name to get NORMAL instead of BlendMode.NORMAL.
color_mode is an IntEnum, so in an f-string it prints as 3. Use .name to get RGB.

Iteration runs from background to foreground. That's the reverse of what the Layers panel shows. Use reversed(psd) if you want panel order.

For a cross-check, here is the same file in Photopea. The panel lists the same three layers, top to bottom, and cuts off the long names. psd-tools gives you the full strings. The small badge on the two upper thumbnails is Photopea's smart object marker, which matches kind == 'smartobject'.

Screenshot: the same PSD opened in Photopea, October 2026

What bbox and offset tell you

A layer's pixels only cover its bounding box, not the whole canvas. In this file only the background fills the canvas. The plant layer is 624×665 pixels placed at (110, 474). The text layer is 756×422 at (123, 0).

Each layer's bbox on the canvas, drawn from the script output. Boxes only, no layer pixels.

This matters as soon as you export. If you build sprites or web assets from layers, store the offset next to each PNG, or you lose the position.

Extract every layer as a transparent PNG

layer.composite() renders one layer, with its mask and clipping layers, as an RGBA Pillow image cropped to its bbox. The script below skips groups, names files by index plus a slug of the layer name, and prints what it wrote:

import re
from pathlib import Path
from psd_tools import PSDImage

psd = PSDImage.open("poster.psd")
out = Path("layers")
out.mkdir(exist_ok=True)

for i, layer in enumerate(psd.descendants()):
    if layer.is_group():
        continue
    image = layer.composite()          # RGBA, cropped to layer.bbox
    if image is None:                  # empty layer, nothing to draw
        continue
    slug = re.sub(r"[^a-z0-9]+", "-", layer.name.lower()).strip("-")
    path = out / f"{i:02d}-{slug}.png"
    image.save(path)
    print(f"{path}  {image.mode}  {image.size}  offset={layer.offset}")

Each layer exported as a transparent PNG, cropped to its bbox.

Two choices here save you trouble later:

Don't use the raw layer name as a file name. Layer names are free text. Two layers can share a name, and psd-tools happily accepts a name like 'Logo / v2'. The README example saves to "%s.png" % layer.name, which fails on the first slash.
Use composite(), not topil(), for anything you'll show. topil() returns the raw pixel data without applying the mask. composite() applies the mask and clipping. If you'd rather work in NumPy, layer.numpy() gives the raw pixels as floats from 0 to 1. For the plant layer that's a (665, 624, 4) float32 array.

If you need every layer at full canvas size, for example to stack them in CSS with no offsets, pass the document viewbox:

placed = plant.composite(viewport=psd.viewbox)  # 880x1216, transparent around the plant

Get the original file out of a smart object

A smart object layer wraps a whole embedded file, and Photoshop draws it scaled into the layer's box. layer.composite() gives you what's on the canvas. layer.smart_object gives you the embedded file itself, at its own size:

from pathlib import Path
from PIL import Image
from psd_tools import PSDImage

psd = PSDImage.open("poster.psd")
out = Path("originals")
out.mkdir(exist_ok=True)

for layer in psd.descendants():
    if layer.kind != "smartobject":
        continue
    so = layer.smart_object
    so.save(directory=out)                  # writes the embedded file under its own name
    with so.open() as f:                    # file-like object over the same bytes
        embedded = Image.open(f).size
    print(f"{so.filename}: {so.kind} {so.filetype} "
          f"embedded={embedded} placed={layer.size}")

Each smart object holds a PNG larger than the box it is placed in.

In this file both embedded PNGs are bigger than their boxes: the plant is 769×821 inside a 624×665 box, and the text block is 1044×584 inside 756×422. If you're building assets for retina screens, or you want to scale a layer up later, save the embedded file instead of the canvas render.

A few things to know:

so.kind is data when the file is embedded, and external or alias when it's linked. A linked file isn't in the PSD at all; psd-tools only reads it from the working directory unless you pass external_dir=.
so.save() with no arguments writes to the current directory under so.filename. psd-tools strips path tricks like ../ from that name, but it's still whatever the file says, so two layers can overwrite each other. In a server, pass your own filename=.
so.transform_box gives the four corners on the canvas. Here it's a plain rectangle, (110, 474) to (734, 1139) for the plant. A rotated or skewed smart object won't be.

Convert the whole PSD to PNG

psd.composite() returns the full image. By default, though, psd-tools doesn't render anything when the file has a stored merged image and you haven't edited it. It returns that stored image as is. In psd-tools 1.26.0 the check is has_preview() and not is_updated(). Passing ignore_preview=True, force=True or a layer_filter skips it.

You can see the difference on the sample file:

from psd_tools import PSDImage

psd = PSDImage.open("poster.psd")

preview = psd.composite()
print("default :", preview.mode, preview.size, preview.getextrema())

render = psd.composite(ignore_preview=True)
print("rendered:", render.mode, render.size, render.getextrema()[:3])
render.save("poster.png")

default : RGB (880, 1216) ((0, 255), (2, 255), (5, 254))
rendered: RGBA (880, 1216) ((0, 255), (2, 255), (4, 254))

Here the two agree: no pixel differs by more than 1 out of 255. The default call is just reading the stored image, while the second one actually draws the three layers. The psd-tools command line tool takes the same shortcut, so psd-tools export poster.psd out.png wrote the stored RGB image. macOS Quick Look also shows that stored image. It can't show layers.

Two rules follow from this:

Use ignore_preview=True when the layers are what you care about. The stored image is whatever the last app to save the file wrote. If a tool edits the layers and doesn't refresh it, the default call returns the old picture. Rendering costs more time, but the output always matches the layers.
Don't assume the mode. The stored image came back RGB and the render came back RGBA. Call .convert("RGB") before saving a JPEG.

The psd-tools renderer isn't Photoshop's engine. Its docs say most layer effects aren't supported, and only some adjustment layers are (Brightness/Contrast, Levels, Curves, Exposure, Invert, Posterize, Threshold). Check the output for files that use effects.

Batch convert a folder of PSDs to PNG

The ignore_preview=True rule matters even more in a batch, because one file with a stale stored image is easy to miss among hundreds. The loop matches .psd and .psb in any letter case, and wraps each file in try, so one broken upload doesn't stop the run:

from pathlib import Path
from psd_tools import PSDImage

src, out = Path("psds"), Path("png")
out.mkdir(exist_ok=True)

for path in sorted(p for p in src.iterdir() if p.suffix.lower() in {".psd", ".psb"}):
    try:
        psd = PSDImage.open(path)
        psd.composite(ignore_preview=True).save(out / f"{path.stem}.png")
        print("ok  ", path.name, psd.size)
    except Exception as err:   # one bad file shouldn't stop the batch
        print("fail", path.name, type(err).__name__)

I ran it on a folder holding the sample and a copy I cut off after 200 KB on purpose:

ok   poster.psd (880, 1216)
fail truncated.psd OSError

Hide a layer and render again

You can leave a layer out in two ways. A layer_filter decides at render time and leaves the document alone. Setting visible = False changes the document, and that change also turns off the stored-image shortcut:

from psd_tools import PSDImage

psd = PSDImage.open("poster.psd")
text = next(l for l in psd.descendants() if l.name.startswith("Poster text"))

# Option 1: filter at render time; the document is left alone
img = psd.composite(layer_filter=lambda l: l.is_visible() and l is not text)
print("filtered:", img.mode, img.size, "| edited:", psd.is_updated())

# Option 2: hide the layer, which marks the document as edited
text.visible = False
print("hidden  : edited:", psd.is_updated())
psd.composite().save("poster-no-text.png")

filtered: RGBA (880, 1216) | edited: False
hidden  : edited: True

Both outputs were pixel-identical on this file. Use the filter when you render several variants from one open file, such as a version without text for each language.

One detail: visible is the layer's own flag, while is_visible() also checks whether the parent group is visible. Filter on is_visible().

Crop to a layer's bbox and make thumbnails

The bbox is also a ready-made crop box for the rendered page. That gives you three different images of the same layer:

page = psd.composite(ignore_preview=True)
plant = psd[1]

alone  = plant.composite()                       # the layer by itself, trimmed
placed = plant.composite(viewport=psd.viewbox)   # the layer by itself, full canvas
region = page.crop(plant.bbox)                   # the finished page, cut to that box

thumb = page.copy()
thumb.thumbnail((256, 256))

alone  RGBA (624, 665)
placed RGBA (880, 1216)
region RGBA (624, 665)
thumb  RGBA (185, 256)

alone and region are the same size but different images. region includes whatever sits behind and in front of the plant. thumbnail() keeps the aspect ratio, so 880×1216 becomes 185×256.

How psd-tools handles groups, smart objects, text and adjustment layers

In psd-tools, layer.kind is the class name in lowercase with "layer" removed. That's the rule in psd_tools/api/layers.py in 1.26.0. My sample file only has pixel and smart object layers, so the other rows in the table below come from the docs and the source, not from this file:

What it is in Photoshop	`kind`	What to know
Normal raster layer	`pixel`	`composite()` works as shown above
Layer group (folder)	`group`	No pixels of its own. Its bbox is the union of its children. Iterate it, or use `descendants()`
Text layer	`type`	`layer.text` gives the string, `layer.typesetting` the fonts and sizes. Font rendering is listed as not supported, so check text layers in the composite output
Vector shape	`shape`	Needs `psd-tools[composite]` to draw strokes and fills
Smart object	`smartobject`	`composite()` draws it at its box size; `layer.smart_object` gives the embedded file at full size (see above)
Fill layer	`solidcolorfill`, `gradientfill`, `patternfill`	Gradients and patterns need the composite extra
Adjustment layer	the adjustment's name, e.g. `brightnesscontrast`, `curves`, `huesaturation`	There's no single `adjustment` kind. Test with `isinstance(layer, AdjustmentLayer)`, imported from `psd_tools.api.layers`

To see groups for real, I wrapped the two artwork layers in a group in memory (the file on disk isn't changed):

group = psd.create_group(layer_list=[psd[1], psd[2]], name="Artwork")
print("top level  :", [layer.name for layer in psd])
print("descendants:", [layer.name for layer in psd.descendants()])
print("group:", group.kind, group.bbox, group.has_pixels())

top level  : ['Background', 'Artwork']
descendants: ['Background', 'Artwork', 'Monstera potted plant illustration', 'Poster text and badge elements']
group: group (110, 0, 879, 1139) False

A top-level loop would have exported "Artwork" and skipped both children. descendants() returns the group itself too, which is why the export script skips is_group().

Reading PSDs uploaded by users

If your backend opens PSDs that strangers upload, set psd-tools parse limits. A PSD can declare far more pixels than it contains, so a small upload can ask for gigabytes when rendered. psd-tools caps each estimated allocation at 4 GiB by default and has parse limits you can tighten:

from psd_tools import ParseLimits, PSDImage

psd = PSDImage.open(
    "poster.psd",
    parse_limits=ParseLimits(max_read_bytes=64 * 1024**2,
                             max_total_bytes=256 * 1024**2),
    max_alloc_bytes=512 * 1024**2,
)

Going over a limit raises an error you can catch and turn into a 4xx response. Byte limits are off by default, so set them yourself. The Handling untrusted files page lists every setting.

What if you only have a flattened PNG?

psd-tools can only read layers that already exist in the file. A flattened PNG or JPEG has no layer records, so there is nothing for descendants() to return. You can cut the elements out by hand in an editor. Or you can run the flat file through an image to layers converter first, then point the scripts above at the PSD it gives you.

One option is IntoLayers, which I work on. It is an AI image-to-layers converter that splits a flattened PNG or JPEG into a rebuilt background plus a separate transparent layer for each element — text, subjects and graphics — and exports them as a layered PSD, transparent PNGs or a layered SVG. What to expect before you wire it into a pipeline:

Input is one PNG or JPEG per run, up to 10 MB.
You choose 2, 3, 5, 7 or 9 layers, or Auto (2–17). The background counts as one.
Text comes back as an image, not live type. In the PSD each element is a smart object holding a PNG, like the two layers above, so in psd-tools a text element is kind == 'smartobject' with no .text attribute.
Anything that was hidden behind another element is a guess, not a recovery.
Your first conversion (1K, 2 layers) runs without an account.

Tool	Language	Good for	Catch
psd-tools	Python	Reading layer data, exporting PNGs, light edits	Its rendering isn't Photoshop's; most effects aren't drawn
ImageMagick / Wand	CLI, Python	Quick `file.psd[N]` frame extraction	Layer frames come out trimmed, and you work by index, not by name
Photoshop scripting (win32com)	Python on Windows	Exact Photoshop output	Needs a licensed Photoshop running
Aspose.PSD for Python	Python (.NET)	Commercial SDK with editing	Paid licence; a temporary licence is offered for trials
ag-psd	JavaScript	Reading and writing PSDs from JavaScript	Not Python; its README says text layer support is incomplete

FAQ

Can psd-tools edit text in a PSD?

No. You can read a text layer's string and styles, but the README lists editing text in type layers and font rendering as not supported. It has limited support for editing layer names and for adding or removing pixel layers and groups.

Why is my psd.composite() output black or different from Photoshop?

psd.composite() returns the merged image stored in the file unless you've edited the document. If that stored image is blank or out of date, so is your output. Pass ignore_preview=True to render from the layers. Remaining differences usually come from layer effects psd-tools doesn't draw.

Can psd-tools open PSB (large document) files?

Yes. The 1.26.0 source describes PSDImage as a "Photoshop PSD/PSB document", and psd.version tells you which one you opened: 1 for PSD, 2 for PSB. I only had a PSD to test with, so the snippets above were run on PSD alone.

Does psd-tools need Photoshop installed?

No. psd-tools reads the file format itself, so Photoshop is never involved. You need Python 3.11 or newer. Photopea or GIMP are handy for checking output by eye.

How do I convert a PSD to PNG in Python?

PSDImage.open("file.psd").composite(ignore_preview=True).save("file.png"). For one PNG per layer, use the export loop above.

Disclosure: I work on IntoLayers.

How to Draw a LaTeX Syntax Tree with the forest Package

libersand — Sun, 25 Oct 2026 08:08:13 +0000

To draw a LaTeX syntax tree, load \usepackage[linguistics]{forest}, write the tree as labeled brackets inside a forest environment, give every word its own brackets, add roof for triangles, then name two nodes and join them with \draw for movement arrows. Compile with pdflatex.

This guide is for syntax students who hand in homework or a thesis typed in LaTeX. One sentence runs through every step: the statement The students will read the paper and its question form Which paper will the students read? Every code block below was compiled with pdflatex (TeX Live 2026, forest 2.1.5) on the free TeXLive.net online compiler on 25 October 2026. The broken examples in Step 7 were compiled too, so the error messages are copied from real logs.

Step 1: Load forest with the linguistics library

Put one line in your preamble: \usepackage[linguistics]{forest}.

The forest package is a TikZ-based package for drawing linguistic trees, written by Sašo Živanović and distributed on CTAN under the LaTeX Project Public License. The linguistics option loads a small library that changes three defaults, per the forest manual (section 4.1). Branches meet under the parent node (sn edges), the top of the tree lines up with your example number, and node labels can run over several lines. The same library defines roof, which you need in Step 5.

Example: a minimal document that compiles on its own:

\documentclass{article}
\usepackage[linguistics]{forest}
\begin{document}
\begin{forest}
[TP [DP] [T$'$ [T] [VP]]]
\end{forest}
\end{document}

No TeX installed? Overleaf and TeXLive.net compile the same file in the browser. \documentclass[border=8pt]{standalone} crops the PDF to the tree, which is how the images in this guide were made. Convert that PDF to PNG to put the tree into Word or Google Slides.

Check: you get a small tree with TP on top and DP, T′ under it.

Step 2: Get a labeled bracket string for your sentence

Before any LaTeX, you need the analysis written as labeled brackets: [TP [DP the students] [T' [T will] [VP [V read] [DP the paper]]]].

The forest package only typesets the syntax tree you give it. It does not parse English. Getting the brackets right is the syntax part of the homework. Turning them into a picture is the typing part.

Example: there are three common ways to get the string.

Write it by hand. Draw the tree on paper first, then type it top-down, one bracket per node. This is the only route that shows your own analysis, so it is the one most instructors expect.
Use a free bracket previewer. Several web pages turn a bracket string into a tree picture as you type. They are good for catching a misplaced bracket, but you still write the brackets yourself.
Start from a plain sentence. Some tools take the sentence, write the analysis, and draw it. Vizcept, a syntax tree generator, works this way: you type the sentence, pick Traditional, X-bar or Minimalist labels, and the tree is typeset from code. Paid plans can copy the labeled bracket string or forest code. If you already have a labeled bracket string, paste it instead and the tree is drawn exactly as written. Plans start at $14.90 a month, and you can try the first tree free as a watermarked PNG. The copied forest code leaves out movement arrows and there is no .tex file export, so you still add arrows yourself with \draw (Step 6).

Starting from a plain sentence instead of brackets. Screenshot of Vizcept's tool page, October 2026.

Check: count the brackets. Every [ needs a matching ], and every node has exactly one label. Whatever produced the string, compare it with your own analysis before you hand it in. The tree is only as right as the analysis.

Step 3: Convert the bracket string into forest code

Keep the labels and the nesting, and change two things: put every word string in its own brackets, and write primes in math mode.

In a plain labeled bracket string, [DP the students] means "a DP node with the words the students under it". forest reads the same text as one node whose label is "DP the students". When we pasted the string from Step 2 into forest unchanged, it compiled without a single error and drew nodes labeled "DP the students" and "V read". No error message tells you something is wrong. A bare T' prints a curly apostrophe (T’) instead of a prime (T′), so write T$'$.

Example: the bracket string from Step 2, converted:

\begin{forest}
[TP
  [DP [the students]]
  [T$'$
    [T [will]]
    [VP
      [V [read]]
      [DP [the paper]]]]]
\end{forest}

Same tree, two notations: forest needs the words in their own brackets and the prime written as T$'$. Diagram drawn for this guide.

Check: each word or word group sits at the bottom of its own branch. Spaces and line breaks between brackets do not matter, so indent one level per node. That makes a missing ] easy to spot. Blank lines are the exception (see Step 7).

Step 4: Build the X-bar layers of the syntax tree

In X-bar theory, every phrase XP has an intermediate X′ level between the phrase and its head X.

X-bar theory builds every phrase from the same schema: a specifier, an X′ and a complement. The forest manual opens its decoration section with exactly this XP, specifier, X′, complement template. Your instructor will check that each projection is there, even when it does not branch.

Example: the same sentence with D′, N′ and V′ added. The first line puts every word on the same baseline. It uses where n children=0{tier=word}{}, the manual's example (12), which assigns all nodes with no children to one tier:

\begin{forest}
where n children=0{tier=word}{}
[TP
  [DP
    [D$'$
      [D [the]]
      [NP [N$'$ [N [students]]]]]]
  [T$'$
    [T [will]]
    [VP
      [V$'$
        [V [read]]
        [DP
          [D$'$
            [D [the]]
            [NP [N$'$ [N [paper]]]]]]]]]]
\end{forest}

The Step 4 code as pdflatex renders it, with terminals aligned by tier=word. Compiled on TeXLive.net, October 2026.

Check: trace each head up to its phrase. N goes to N′ goes to NP, D goes to D′ goes to DP, V goes to V′ goes to VP. If one link is missing, a bracket is in the wrong place.

Step 5: Add triangles to a syntax tree with roof

Add roof after the words of a phrase you do not want to analyze: [DP [the students, roof]].

A full X-bar syntax tree gets tall fast. When a phrase's inside does not matter for the point you are making, linguists draw a triangle over its words. In forest the comma after the words starts the node's options, and roof is an option from the linguistics library. The Forest Quickstart Guide for Linguists (section 5) shows the same pattern.

Example: both DPs as triangles, so the tree only shows what matters for the clause:

\begin{forest}
[TP
  [DP [the students, roof]]
  [T$'$
    [T [will]]
    [VP
      [V$'$
        [V [read]]
        [DP [the paper, roof]]]]]]
\end{forest}

Check: the triangle spans the words, and its top point touches the DP label. A long phrase makes a wide triangle. The quickstart guide's fix is a line break inside the label, as in [walked \\ the dog, roof].

Step 6: Add traces and movement arrows to a syntax tree

Give the moved phrase and its trace a name, then draw an arrow between the two names with TikZ after the tree's last bracket.

The forest package has no built-in movement command. Instead, any node can get a TikZ name, and the \draw command can connect two names. In Which paper will the students read? two things move. The wh-phrase goes from object position to Spec-CP, and will goes from T to C.

The forest manual's movement example: name two nodes, then \draw between them. Source: forest documentation, p. 8, by Sašo Živanović, LaTeX Project Public License 1.3.

Example: traces are written as $t_i$ and $t_j$ , with matching subscripts on the moved items:

\begin{forest}
[CP
  [DP [which paper$_i$, roof, name=wh]]
  [C$'$
    [C [will$_j$, name=aux]]
    [TP
      [DP [the students, roof]]
      [T$'$
        [T [$t_j$, name=auxtrace]]
        [VP
          [V$'$
            [V [read]]
            [DP [$t_i$, name=whtrace]]]]]]]]
\draw[->] (whtrace) to[out=south west, in=south] (wh);
\draw[->] (auxtrace) to[out=south west, in=south] (aux);
\end{forest}

The Step 6 code compiled: wh-movement to Spec-CP and T-to-C movement, drawn with \draw. Compiled on TeXLive.net, October 2026.

Check: each arrow starts at a trace and ends under the phrase that moved. out= and in= set the angle the curve leaves and enters. In the compiled tree the will arrow crosses the subject triangle; changing the out= and in= angles moves the curve if you want it clear. Some textbooks strike through the lower copy instead of writing t. \sout{the paper} does that, and it needs \usepackage[normalem]{ulem}.

Step 7: Fix the compile errors you will hit first

When forest fails, read the first line that starts with ! in the log. The table below lists the messages pdflatex printed for seven common mistakes.

Mistake	Error message (first line)	Fix
A blank line inside `forest`	`Paragraph ended before \forestOappto was complete.`	Delete empty lines inside the environment
A comma in a label, like `[NP, PP]`	`I do not know the key '/tikz/PP'`	Wrap the label in braces: `[{NP, PP}]`
`roof` with plain `\usepackage{forest}`	`I do not know the key '/tikz/roof'`	Load `\usepackage[linguistics]{forest}`
`\draw` without the final `;`	`Giving up on this path. Did you forget a semicolon?`	End every `\draw` with `;`
`\draw` placed after a node without braces	Same semicolon message	Wrap code after a node in `{ }`, or move it after the last `]`
One `]` missing	`Argument of \bracket@Parse@token has an extra }.`	Count brackets, or indent one level per node
`\sout` without ulem	`Undefined control sequence.`	Add `\usepackage[normalem]{ulem}`

Two of these are easy to misread. The comma error names PP as an unknown key because forest reads everything after a comma as options. The unbraced \draw reports a missing semicolon even when the semicolon is there. The manual's warning is that TikZ code after a node "should usually be enclosed in braces to hide it from the bracket parser".

Is forest better than qtree or tikz-qtree for syntax trees?

For most syntax homework, forest is the safer choice, but qtree is closer to the bracket notation you already know. qtree (version 3.1b, 2008) writes a node as [.VP ... ], with a dot before each label and words separated by spaces. That is almost the labeled bracket string unchanged. Its manual limits trees to 20 levels and five branches per node. tikz-qtree keeps the qtree syntax and draws with TikZ, which adds arrows between nodes. forest uses its own bracket syntax, has a packing algorithm its manual describes as producing very compact trees, and has the linguistics library with roof and c-command helpers. If a classmate's template uses \Tree [.S ...], that is qtree or tikz-qtree, and it will not paste into a forest environment as is.

FAQ

How do I create a tree in LaTeX?

Load \usepackage[linguistics]{forest}, then write the tree inside \begin{forest} ... \end{forest} with one pair of square brackets per node, label first. Words go in their own brackets under their category. Compile with pdflatex. Overleaf has a ready-made forest syntax tree template.

How do you do a syntax tree?

Find the main verb and its arguments, group words into phrases around their heads (NP, VP, PP), then attach the phrases to a clause node (S, TP or CP) from the bottom up. Write the result as labeled brackets and check that every word appears once, left to right, along the bottom.

Why do my nodes show "DP the students" instead of a branch?

The forest package treats everything before the first nested bracket as one label, so [DP the students] becomes a single node. Put the words in their own brackets, [DP [the students]], and the DP gets a branch down to the words.

Disclosure: written by the team behind Vizcept.

How to Schedule AzuraCast Jingles and Station IDs

libersand — Sat, 24 Oct 2026 06:35:15 +0000

To schedule AzuraCast jingles, give each kind of cut its own playlist. Set short IDs to "Once per x Songs", shuffled, and the top-of-hour ID to "Once per Hour" at minute 0. Tick "Hide Metadata from Listeners ('Jingle Mode')" and leave the Advanced tab's scheduling boxes off.

The rest of this guide explains why each setting matters, using one real support thread as the running example. In GitHub discussion #7042, a broadcaster had a jingles playlist scheduled from 5 a.m. to midnight, set to play once every 4 songs, and it never played. The accepted answer pointed to a single checkbox. You'll see which one in Step 4.

The support thread used throughout this guide. Source: AzuraCast discussion #7042.

Before you start

You need three things in place before you set up AzuraCast jingles:

A running AzuraCast station. The Docker install is the standard route, and any user role with the "Manage Station Media" permission can edit playlists.
At least one General Rotation playlist with music in it, so the AutoDJ always has something to fall back on.
Your finished jingle files: MP3 or WAV, already mixed, one file per cut.

Labels and behavior below were checked against AzuraCast 0.23.9 and the rolling release on the public demo on 2026-10-24. The examples use a made-up station, Copper Pines FM.

Step 1: Make the station ID audio first

Finish and tag every cut before you open AzuraCast. The scheduler can't fix a quiet ID or a missing name.

There are three common ways to get the audio:

Record it yourself. Free, and it sounds like you. Room noise and level matching are your problem.
Hire a voice artist or an imaging company. A human voice, and singing if you want it. Expect to wait for delivery and pay per package.
Use an AI voice tool. Generic text-to-speech gives you a bare voice that you still mix with music yourself. Radio-specific tools mix it for you. One example is JingleLark, which we build: type the script, pick one of 24 radio voices, and it adds an intro, a background bed and an outro, normalized to −16 LUFS, as an MP3 or WAV. Packs start at $14.90 for 50 credits, paid once with no subscription, and a voiceover of up to 220 characters costs 1 credit. Mixing and downloads are free. It makes voiced IDs only, with no singing, and all 24 voices are native English speakers, so scripts in other languages come out with an accent.

One AI option: script, voice and mix in one screen. Screenshot of JingleLark, October 2026.

Whichever route you take, you want a set of files, not one. Three things decide how well they air:

Level. AzuraCast's own post-processing setting says that "values between -14 and -18 LUFS are common for Internet radio stations" (source). An ID inside that range won't jump out over the music or sink under it.
Tags. AzuraCast reads Title, Artist and Album from the file's tags when you upload (source). Set Artist to Copper Pines FM and give each file a Title that says what it is, such as ID - Top of Hour 01.
File names. Use a prefix per element (toh-, id-, sweep-), so a folder sort groups them.

Whichever route you use to make a station ID for your radio station, make several short versions, so a once-every-4-songs rotation doesn't repeat the same cut every 15 minutes.

Check: play each file next to a song from your library at the same volume. None of them should sound much louder or quieter.

Step 2: Create one AzuraCast playlist per element

An AzuraCast playlist carries one rule, so each element type needs its own playlist.

For Copper Pines FM that means three playlists:

Playlist	Contents	Rule it needs
`IDs - Top of Hour`	Hourly ID with the full station name and city	once per hour, at a set minute
`IDs - Short`	3–5 second name IDs	every few songs
`Sweepers`	Short cuts that bridge two songs	every few songs, at a different interval

Upload the files under Media → Music Files, then add each folder to its playlist. The playlist list has an "Apply to Folders" action for this.

Check: each playlist holds one element type only.

Step 3: Pick the Playlist Type and turn on Jingle Mode

The Playlist Type sets how often a playlist plays. On the Basic Info tab, choose "Song-Based Playlist" as the Source. Then set these fields:

Field (exact UI label)	Top of Hour	Short IDs	Sweepers
Playlist Type	Once per Hour	Once per x Songs	Once per x Songs
Minute of Hour to Play / Number of Songs Between Plays	0	4	3
Song Playback Order	Shuffled	Shuffled	Shuffled
Hide Metadata from Listeners ("Jingle Mode")	On	On	On
Allow Requests from This Playlist	Off	Off	Off

Short-ID playlist settings on the Basic Info tab. Screenshot from the AzuraCast public demo, October 2026.

"Once per x Minutes" is the third option. It counts time instead of songs, which suits stations that mix hour-long DJ sets with three-minute tracks. The numbers above are starting points.

Jingle Mode does more than its label says. In AzuraCast 0.23.9, a track from a Jingle Mode playlist carries a jingle_mode annotation, and the Liquidsoap script sends the previous track's metadata again instead of the jingle's (source). Listeners keep seeing the song that just ended while your ID plays. AzuraCast also marks those plays as not visible in song history (source).

Check: reopen each playlist and confirm Jingle Mode is still on and requests are off.

Step 4: Schedule the playlists and leave the Advanced boxes off

The Schedule tab sets when a playlist is active, and the Playlist Type sets how often it plays inside that window. With nothing scheduled, AzuraCast says the playlist "will play at all times". To limit it, click Add Schedule Item and set a Start Time and End Time, plus optional dates and days of the week.

In #7042, the accepted answer flagged one box on the Advanced tab, under "Advanced Manual AutoDJ Scheduling Options": "Only play one track at scheduled time." That reply explained that this option plays one jingle in the whole 5 a.m. to midnight window and then stops. The suggested setup was Once per x Songs at 4, Shuffled, Jingle Mode on, a schedule of 05:00 to 11:59 PM, and no advanced options. The broadcaster reported back that it worked.

Leave these three boxes off for ID and sweeper playlists. Screenshot from the AzuraCast public demo, October 2026.

The 0.23.9 source agrees with that reply. With single-track on, a playlist that has already played since the start of its current schedule block isn't eligible again (source).

"Interrupt other songs to play at scheduled time" is the other box to leave alone for IDs. When the broadcaster in #7042 tried it, jingles sometimes cut in on top of a song and most of the time didn't play at all.

When two playlists are due at the same time, priority decides which one plays. AzuraCast's playlist docs list the defaults: Once per Hour beats Once per x Songs, which beats Once per x Minutes, which beats General Rotation, and a scheduled playlist beats an unscheduled one of the same type. Song requests always come first. The queue builder in 0.23.9 checks them in that order (source).

AzuraCast's Default Priorities table: hourly beats every-x-songs, which beats every-x-minutes and general rotation. Source: AzuraCast docs (MIT).

Check: for each jingle playlist, the Advanced tab has no boxes ticked.

Step 5: Listen to the live stream for an hour

Listen to the live stream across one top of the hour. Before that, open Broadcasting → Upcoming Song Queue to see what the AutoDJ has lined up and which playlist each item came from.

Expect the hourly ID a little after :00, not exactly on it. The AutoDJ waits for the current song to end, so the ID airs when that song finishes.

Why the top-of-hour ID lands after :00. Illustration, not a measurement.

The 0.23.9 scheduler adds two limits that few guides mention (source):

A Once per Hour playlist is only eligible from its target minute until 15 minutes after it. If a long track is still playing at :15, that hour's ID is skipped.
It won't fire again within 30 minutes of its last play.

To air an ID at both :00 and :30, create two Once per Hour playlists, one at minute 0 and one at minute 30. Another user suggested the same pattern (one playlist per slot) in discussion #8286.

Check: note when the hourly ID aired and count songs between short IDs against your settings.

Why isn't my AzuraCast jingle playing?

When AzuraCast jingles never play, it usually comes down to one of five settings. Check them in this order:

"Only play one track at scheduled time" is ticked. You get one jingle per schedule block. Untick it.
A higher-priority playlist always wins. For example, a Once per Hour playlist with a wide window, or a scheduled playlist that blocks an unscheduled one.
The playlist is outside its schedule, or disabled. Check Start Time, End Time and the days of the week. An end time earlier than the start time means the playlist runs overnight.
A long track runs past the 15-minute window. With hour-long mixes, Once per Hour can miss. Once per x Minutes is more forgiving.
Changes haven't taken effect. In #7042, the answerer said plain playlist edits apply live unless the station uses Manual AutoDJ Mode. A hosting provider's knowledge base says playlists with advanced options need Restart Broadcasting, which drops listeners.

When a queue item looks wrong, open its logs from the Upcoming Song Queue. The log shows why the AutoDJ picked it.

FAQ

What is a station ID on an AzuraCast station?

A station ID is a short audio cut that says your station's name. In AzuraCast it's an ordinary media file in a playlist set to Jingle Mode, and the AutoDJ slots it between songs according to the Playlist Type.

Can AzuraCast play a jingle over the start of a song?

Not out of the box. AzuraCast plays jingles between tracks. Playing a jingle over a song is an open request on the AzuraCast suggestion board (Jingle while a song is played). Power users can write their own Liquidsoap rules with an "Advanced" Playlist Type, which AzuraCast leaves for you to configure by hand.

Can I force a jingle to play right next to another cut?

Yes, with an Advanced playlist and a Liquidsoap rule, added under Broadcasting → Edit Liquidsoap Configuration. The AzuraCast docs give this example for two playlists that should always play back to back:

radio = rotate(weights=[1,1,5], [playlist_commercials, playlist_bumpers, radio])

AzuraCast names each playlist's variable playlist_ plus the name in lowercase, with spaces turned into underscores.

Disclosure: written by the team behind JingleLark.

IntoLayers is live: split any image into editable layers with AI

libersand — Mon, 14 Sep 2026 14:44:44 +0000

I've spent the last few weeks building IntoLayers, an AI image to layers converter, and it's live today.

The problem

You have a finished image — a poster, a flyer, a social graphic someone exported as a flat PNG — and you need to change one thing in it. The text is wrong, the offer changed, the source file is gone. Normally that means masking things out by hand, or regenerating the whole image and hoping nothing else shifts.

What it does

Upload a PNG or JPEG, click Convert, and IntoLayers hands back the design as separate, named, transparent layers instead of one flat image — text, subjects, graphics and a reconstructed background, each on its own layer with the gaps filled in behind whatever it removed.

One poster in, six layers out, as an example:

Poster gradient background
Terracotta flower pot
Monstera plant foliage
Spring sale subtitle
GREEN HOUSE main title
NEW badge

Download any layer on its own as a transparent PNG, or export the whole stack as a single layered PSD that opens straight into Photoshop, Photopea or Affinity Photo.

A few details I cared about

It's not background removal. A background remover gives you one cutout and throws the rest away. This keeps every element as its own layer and rebuilds what was behind it.
PSD packaging happens client-side. The layers get assembled into the PSD file in your browser, so the image isn't re-uploaded anywhere just to zip the layers together.
No account needed to try it. One conversion at 1K is free; signing in unlocks 1.5K/2K output and keeps results in a library.

Who it's actually for

This started from a narrow set of situations that kept coming up: fixing one wrong element in an AI-generated image without regenerating the whole thing, updating an approved campaign visual after the offer changed, or picking up a flyer whose working file walked out the door with whoever made it.

If any of that sounds familiar, I'd like the feedback: intolayers.com. No signup required for the first conversion.

How to Stop an Image Model From Ignoring Your Reference Image

libersand — Fri, 21 Aug 2026 14:16:12 +0000

A user uploaded a floor plan, typed "remove the room labels", and got back the same plan — labels still on it. Tried again, same result.

The interesting part: the model was not ignoring the instruction. Another line in our own prompt was quietly outranking it.

I work on FloorDrafter, an AI floor plan generator. A big part of the product takes a reference image — a photo of a hand sketch, a scanned blueprint, an existing plan — and applies one requested change to it. That turns out to be a much harder prompt problem than generating from scratch, because now the model has two masters: the picture and the sentence.

Here are six things we learned making it behave, plus how we measure whether a prompt change actually helped.

1. Separate "how to draw" from "what to draw"

Our style presets started life as single strings:

top-down 2D color floor plan: flat orthographic overhead view, color-filled rooms… clear room labels and dimension lines with measurements

Looks harmless. But that string got injected into the same block as the user's instruction, under a rule that said everything in the block must be delivered fully and visibly. So the block read:

REQUESTED CHANGE
- Representation: ...clear room labels and dimension lines...
- remove the room labels          <- the user's own words

Two contradictory requirements, both marked mandatory. The style description won, because it was more specific.

The fix was to split every style into two halves: render (viewpoint, line weight, materials, lighting — how to draw) and annotations (room labels, dimension lines — what content to include). The from-scratch branch names both. The edit-an-existing-image branch names only render, because labels and dimensions are content that already exists in the reference — whether they stay is the user's call, not the style preset's.

Generalizable version: if your prompt is assembled from fragments, audit every fragment for whether it smuggles in content requirements. A fragment that describes form is safe to inject anywhere. A fragment that describes content can collide with user intent.

2. Write the rule as "only change what's named", not as a list of prohibitions

The obvious way to protect a reference image is a MUST NOT list: don't move walls, don't resize rooms, don't change the window positions.

That list locks the user out. Someone who wants to "keep the layout but knock down the kitchen wall" now can't, because you preemptively banned it.

Inverting it works better: change only what the instruction names, leave everything else as it is in the reference. The granularity comes from the user's own sentence instead of from your list.

3. Explicitly authorize the requested change, or you get a copy

This one is counterintuitive. After we tightened the fidelity language, output quality went up — and then users started reporting that nothing changed at all. The model had become so conservative it was returning something close to the original image.

Fidelity instructions alone teach the model that changing things is risky. You have to also grant full permission to execute the named change, and add a closing self-check that confirms the change is actually visible. Both halves, or you trade one failure mode for the other.

4. Ban adding, never ban existing

Our closing prohibition originally read, roughly, "no text beyond room labels and dimensions."

Then a user uploaded a full drawing sheet — not a bare floor plan, but a title block, project name, legend, scale bar, north arrow, notes. The model read that prohibition literally and deleted all of it. A real case: a church site plan came back with the main title, the church name, the SIMBOLOGÍA legend, the scale bar, the NOTA block and five bottom notes all gone. The floor plan survived. Everything around it did not.

A prohibition on text cannot distinguish "text you invented" from "text that was already there". So the rule can only forbid adding. Preserving what exists needs its own affirmative clause — and it needs one more sentence that most people miss:

Changing the style is not a reason to delete content.

Without that, picking a monochrome CAD style gets read as "so only keep room labels and dimensions", and you are back to deleting the sheet.

Both clauses shipped, and both are asserted in the test suite described at the end — title blocks, legends, scale bars and note blocks are now on an explicit preserve list, copied verbatim.

5. Some constraints must be immune to your own exemption clauses

Once you have a rule that says "only change what's named", you will naturally write self-checks that begin "Setting aside what the change named…". That phrasing is a loophole.

A user photographed a C-shaped outline, 16 by 24, and wrote "2 units on 1 footprint". The model duplicated the entire C shape and butted the two copies together into a 32 by 24 building. Every dimension label was preserved perfectly. The geometry had doubled.

Two failures stacked here:

The protection clause banned moving the footprint but not duplicating, scaling or extending it.
The self-check started with the exemption phrase, so the model decided the footprint change fell under "what the change named" and skipped the check entirely.

The footprint check had to be rewritten to start with "Regardless of what the change named…". Geometric integrity is not negotiable by the instruction; content is.

There is a second lesson buried in that example. "2 units on 1 footprint" contains a goal (2 units) and a boundary (1 footprint) in one breath. Models reliably grab the goal and drop the boundary, so the prompt has to say out loud that the user's sentence may contain limits, not just targets.

6. A capability needs an exemption in every section that can override it

Back to the labels. "Remove the labels" failed because three separate parts of the prompt each independently reinstated them:

The rule authorized restyling and adding — but never mentioned deleting.
The sheet-protection clause said do not drop, blank out, condense or summarise any existing element.
The closing self-check saw missing annotations and told the model to redo them.

Patch any one of those and the other two still win. Deletion had to be named in all three places at once — and scoped tightly ("delete only what was named; deleting anything else is an error"), because a broad deletion permission takes you straight back to lesson 4.

The pattern: when you add a capability to a long prompt, grep the whole thing for sections that could veto it. Long prompts develop internal politics.

How we know any of this worked

Prompt changes are easy to rationalize and hard to verify. We ran fixed probes: same reference image, same instruction, repeated runs per variant, counting outcomes by hand against the previous prompt. The denominators below count elements rather than runs — dimension-chain segments in the reference, room labels across the probe set, and images in the sweep.

Metric	Before	After
Original dimension chain survives	~0.6 / 9	~7 / 9
Room labels preserved	~5 / 20	~15 / 20
Images with invented dimensions	9 / 10	0 / 10

Those numbers are small-sample and hand-counted. That is fine — they are decision-grade, not paper-grade. The point is that "this prompt feels better" is not a finding, and a fixed probe costs an hour.

Unit-testing a prompt

The six lessons above are all invariants: properties the assembled prompt must have, in every branch, forever. Nothing stops a future edit from quietly removing one — they are just strings in a template.

So they are unit tests now. The prompt builder is a pure function, which makes this cheap:

it('bans only added text, never existing text', () => {
  const p = buildPrompt({ hasReference: true, /* … */ });
  assert.match(p, ADD_ONLY_TEXT_RULE);       // "do not add … text"
  assert.doesNotMatch(p, LEGACY_TEXT_BAN);   // the old blanket ban
});

it('states that a style change is not a reason to delete content', () => { /* … */ });

it('makes the footprint check immune to the change exemption', () => {
  const p = buildPrompt({ hasReference: true, /* … */ });
  assert.match(p, FOOTPRINT_UNCONDITIONAL);  // "regardless of what the change named"
});

There are 28 of them. They do not test the model — they test that the string we send still contains the clauses we worked out. Each one encodes a specific failure mode we found and fixed, so it cannot come back unnoticed.

If you maintain a prompt longer than a screenful, this is the highest-value hour you can spend on it.

The short version

Split prompt fragments into form and content; only form is safe to inject everywhere.
Prefer "change only what is named" over a list of prohibitions.
Grant the change explicitly, or fidelity language will suppress it.
Forbid adding, never forbid existing.
Make integrity constraints immune to your own exemption phrasing.
New capabilities need an exemption in every section that could veto them.
Probe with fixed inputs and count. Then lock the result in with tests.

None of this is specific to floor plans. Any time you send an image plus an instruction and expect the untouched parts to stay untouched, the same failure modes are waiting.

A Postgres driver silently shifted my timestamps by 8 hours — and every test stayed green

libersand — Mon, 17 Aug 2026 14:14:55 +0000

A chunk of the timestamp columns in my database were quietly wrong.

Not corrupted. Not null. Just — eight hours off. The values looked perfectly reasonable in psql. They looked reasonable in the app. They were reasonable, for a timezone I wasn't in.

Every test passed. CI was green. It had been green the whole time.

Here's what was actually happening, and why it's invisible to most of the people who could have warned me.

The setup

Nothing exotic:

Postgres
postgres.js as the driver
Drizzle ORM on top

The schema looked like this — and if you use Drizzle, yours probably does too:

export const user = pgTable('user', {
  id: text('id').primaryKey(),
  createdAt: timestamp('created_at').notNull(),
  updatedAt: timestamp('updated_at').notNull(),
});

That timestamp('created_at') is the important part. In Drizzle, timestamp() with no options generates a Postgres timestamp without time zone column — not timestamptz. The default is the unsafe one.

Two things that are individually fine

One: timestamp without time zone stores no offset.

That isn't a bug, it's the definition of the type. Postgres stores the wall-clock digits you gave it — 2026-08-17 10:00:00 — and nothing else. No zone, no offset. It has no idea whether that's 10am in Shanghai or 10am in Chicago, and it doesn't care.

Two: the driver has to guess on the way back.

When you hand postgres.js a JavaScript Date, it serializes it and sends it over. Postgres receives a value for a timestamp without time zone column, discards the offset, and stores the literal wall clock.

Then you read it back. Postgres hands the driver a bare string with no zone marker. The driver has to turn that into a JS Date, and it has no offset to work with — so it resolves the string against the runtime's local timezone.

Which is not necessarily the timezone the value was written in.

The round trip

My laptop is UTC+8. Trace one value through:

Step	Value
`new Date()` in my app	18:00 Beijing = 10:00 UTC
Driver serializes, Postgres strips the offset	stored as `10:00`
Read back: bare string, no zone	`2026-08-17 10:00:00`
Driver resolves against local time (UTC+8)	10:00 Beijing = 02:00 UTC

Wrote 10:00 UTC. Read 02:00 UTC.

Eight hours. And it compounds — write that value back and you lose another eight.

The number isn't special. It's just my UTC offset. In New York it would be five hours, in the other direction. In London during summer, one.

And in UTC it is zero.

Which is why every test passed

Read that last line again, because it's the whole story.

GitHub Actions runners: UTC
Your Docker container, unless you went out of your way: UTC
Your production server: almost certainly UTC

When the local offset is zero, the write-side and read-side interpretations agree exactly. The bug doesn't produce a small error under UTC. It produces no error at all. This isn't a flaky test or a rare edge case — in a UTC environment the behavior is genuinely, completely correct.

So my test suite wasn't failing to catch a bug. It was running in the one environment where the bug does not exist.

There is exactly one way to trigger it: run code that reads and writes timestamps from a machine whose clock isn't UTC. A developer laptop. Which is precisely what I did.

The expensive version

I needed to backfill a column — copy timestamps from an old table into a new one. Straightforward script: read rows, transform, write rows.

I ran it from my laptop.

Every row it touched moved eight hours. The script was correct. The logic was correct. It would have been fine on the server. It just happened to make a round trip through a JavaScript runtime sitting in UTC+8, and paid the toll on the way through.

The rule I now follow without exception:

A backfill must never round-trip a timestamp through the application layer. Copy it inside the database.

UPDATE new_table n
SET created_at = o.created_at
FROM old_table o
WHERE n.id = o.id;

Postgres moving a value from one column to another cannot get the timezone wrong, because no timezone is ever inferred. There is no JS runtime in the path to guess with.

Fixing it going forward

Use timestamptz. In Drizzle:

createdAt: timestamp('created_at', { withTimezone: true }).notNull(),

timestamptz doesn't actually store a timezone either — that's a common misconception; Postgres normalizes to UTC internally. But the wire format carries an offset in both directions, so the driver never has to guess. The round trip becomes lossless no matter what timezone anything is running in.

Audit what you already have. My schema turned out to be a mix: a handful of newer tables had withTimezone: true and everything older didn't. Nothing in the application code distinguishes them. This finds them:

SELECT table_name, column_name, data_type
FROM information_schema.columns
WHERE data_type LIKE 'timestamp%'
ORDER BY data_type, table_name;

Set TZ=UTC for your local runtime. This is a band-aid, not a fix — it makes your laptop behave like CI, which hides the bug rather than removing it. But it stops you from making things worse while you migrate.

What I actually took away

I had assumed a green test suite meant the code was correct. What it actually meant was: the code is correct in the environment the tests run in.

Timezone is an ambient property of the machine, not an input to my tests. So is locale. So is filesystem case sensitivity. So is CPU architecture. My CI wasn't wrong — it just isn't a laptop in UTC+8, and it never will be.

If your infrastructure is UTC top to bottom and your team isn't, that gap is where this class of bug lives. You don't close it by writing better tests. You close it by not letting the ambient environment participate in the answer — which, for timestamps, means timestamptz and doing data migrations in SQL.

I'm an indie developer running several small SaaS products solo. This one cost me a day and a data migration, so I figured I'd write it down.