The Zouti Photos Template Language

A template is a small pattern that turns one photo’s metadata into a piece of text. It is ordinary text with fields in braces mixed into it: everything outside the braces is copied through exactly as typed, and each {…} is replaced with something from the photo.

{created.year} — {title,Untitled}
 │               │      │
 │               │      └─ used when the field has no value
 │               └─ the photo's title
 └─ the year the photo was taken

──▶  2026 — Sunset over the bay

Zouti Photos implements the osxphotos Metadata Template Language. Templates written for one usually work in the other; the differences are listed at the end.

Every example on this page is real output. They were rendered by the template engine against the same example photo, described under The example photo.

Contents

• Where templates are used
• Quick start
• The parts of a field
• When a field has no value
• When a field has several values
• Field arguments
• Filters
• Find and replace
• Tests and yes/no text
• Combining two lists
• Variables
• Escaping
• Format codes
• The order things happen in
• Field reference — every field
• Filter reference — every filter
• Cookbook
• Errors
• Limits
• Differences from osxphotos

Where templates are used

A saved export keeps its templates with it, so the Run Saved Export Shortcuts action and the AppleScript interface use whatever was saved.

The language is identical everywhere. Three things depend on where a template runs:

• Empty fields. In an export name an empty field renders _, so you never get a silently blank filename. In Bulk Edit — where an empty result means “leave this photo alone” — it renders as nothing. See When a field has no value.
• /. A slash makes a folder level only in an export folder template. Everywhere else it stays part of the text.
• {counter} and {id} count position within the current run — the export, or the rows of the bulk-edit sheet.

Quick start

Six templates that cover most of what people want:

On a photo with no album, no place and no favorite flag, the same templates render 2026/No Album, All Photos/2026 and Unknown Country/Unknown City — that is what the comma slot is for.

The parts of a field

Everything so far has used the two most common parts of a field: its name and its default. A field can carry more, always written in this order:

{ delim+ field (arg) |filter [find,replace] test &more ?yes ,no }

  delim+          join this field's values into one value
  field           what to insert — the only required part
  (arg)           an argument, for the fields that take one
  |filter         change the value; chain as many as you like
  [find,replace]  replace text inside the value
  test            a comparison — the space before it matters
  &more           add another template's values to the list
  ?yes            text to use when the result is true
  ,no             text to use when it is false or empty

A colon after the field name carries a format code ({counter:05d}), except on the handful of fields that give the colon slot another meaning ({format:int:03d,…}, {created.strftime,…}).

Every part except the field name is optional, and most templates use none of them.

When a field has no value

Not every photo has a title, a place, or an album. Add a comma inside the braces to choose what to write instead — and note the replacement can be another template rather than plain text.

{title,{original_name}}
 │     │
 │     └─ a default can itself be a template
 └─ use the photo's title

On a photo with no title:

An explicitly empty default renders nothing at all, in either context: {title,} leaves the spot blank rather than writing _.

A false yes/no field counts as “no value.” {hdr} on a non-HDR photo renders _, not False — so {hdr,SDR} is how you label the other case. A true one renders the literal True.

When a field has several values

A photo can be in several albums and carry several keywords and people. A field like that produces a list, and what a list does depends on where the template is used:

Lists multiply when two of them appear in one template:

Six copies of a photo is rarely what anyone wants, so collapse a list to one value before it multiplies. There are two ways:

delim+ joins in place, before the filters run:

|join(x) joins later, after the other filters:

The difference is when: {,+keyword|upper} joins first and then upper-cases the whole string, while {keyword|upper|join(,)} upper-cases each keyword and joins afterwards. They agree here, and stop agreeing as soon as a filter treats one long string differently from several short ones.

Multi-value fields: {keyword}, {album}, {folder_album}, {person}, {label}, {label_normalized}, {detected_text}. Everything else renders one value or none.

Field arguments

A few fields accept an argument in parentheses.

{folder_album} renders an album’s full path in the Photos sidebar, joined with / so an export folder template recreates your library’s folder tree. Pass a different separator to use it in a filename instead:

A / inside a folder or album title is part of the name, not a level of nesting, and is rewritten to - so it cannot split the path.

{counter(start,stop,step)} configures a counter — see Counters.

Filters

A filter changes a value after the field produces it. Append it with |, and chain as many as you like — they run left to right, each working on what the last handed it.

{person|sort|uniq|join(, )}
        │    │    └─ …joined with a comma and a space
        │    └─ …duplicates dropped…
        └─ people sorted…

Filters come in two kinds, and the distinction matters:

• Text filters work on each value — {keyword|upper} on three keywords gives three upper-cased keywords.
• List filters work on the list as a whole — {keyword|join(-)} gives one value.

Two pairs are easy to confuse:

The s in appends/prepends is for string.

A filter argument may itself be a template. {keyword|join({comma})} joins with a comma, and {keyword|append({person})} adds the face names to the keywords. append, prepend and remove use every value the argument renders — and none, if it renders nothing, so a photo with no faces simply keeps its keywords. Every other filter needs its argument to come to exactly one value. To put a literal brace in an argument, escape it: {title|appends(\{draft\})} → Sunset over the bay{draft}.

The complete list is in the Filter reference.

Find and replace

Square brackets after the field replace text inside each value. Separate several pairs with |.

An empty replacement deletes the found text. Find and replace runs before the filters, so {album[Beach,Shore]|lower} replaces first and lower-cases the result.

Tests and yes/no text

A field can be used as a question rather than as text. Follow it with ?, and the template writes one thing when the answer is yes and another when it is no.

{favorite?Favorites,Everything Else}
 │        │         │
 │        │         └─ used when it is false
 │        └─ used when the field is true
 └─ a yes/no field: is the photo a favorite?

{hdr}, {favorite}, {hidden} and {edited} are true/false fields. Any other field counts as true when the photo has a value for it, so {title?Titled,Untitled} sorts photos by whether they have a title at all.

For anything finer, write a comparison between the field and a value. The space before the comparison word is required — it is what separates the test from the field name.

{keyword contains Beach?At the Beach,Elsewhere}
 │       │        │     │            │
 │       │        │     │            └─ used when it does not
 │       │        │     └─ used when the test passes
 │       │        └─ the value compared against
 │       └─ the comparison (a space before it is required)
 └─ the field being tested

Every operator can be reversed with not in front of it. On a multi-value field the test passes when any value satisfies it.

Several candidates can be tested at once by separating them with |: {keyword contains Beach|Ocean?Coastal,Inland}.

Combining two lists

& appends a second template’s values onto the first field’s list. It is the way to build one list out of two.

Either side may be empty: a photo in no albums contributes only the face names, and one with neither falls back to the expression’s own default. Chain three lists by nesting: {keyword&{folder_album(>)&{person}}}.

In a name template remember the result is a list, so the photo is exported once per value; in the sidecar keyword template and in Bulk Edit, several values is exactly the point.

& or |append(…)?

{field|append({other})} joins two lists too, and mostly they are interchangeable. One difference decides it: filters run before &, so a filter written after a combine is not applied to the combined list at all — it lands inside the operand as literal text.

So: reach for & when you just want the two lists side by side, and for |append(…) when anything has to happen to the result afterwards. |append also chains, which is the tidiest way to merge three lists:

{keyword|append({label})|append({person})|uniq}
──▶  Travel + Vacation + Beach + Sunset + Sky + Katie + Suzy

Variables

A template can name a value and reuse it later in the same template. {var:NAME,VALUE} defines one and writes nothing itself; {%NAME} reads it back.

• Names may contain letters, numbers and underscores, and must be defined before they are used. A variable lives for one render of one template.
• A variable keeps its list of values and can be filtered when read.
• A variable holding nothing contributes nothing.
• %NAME — without braces — also works inside a join delimiter, a find/replace pair, and a filter argument. In the first two it must come to exactly one value; append, prepend and remove accept a list. Write %% for a literal percent sign in those three places only — everywhere else % is already ordinary text.
• Variables are deliberately absent from the graphical builder.

Since a filter argument can be a template, a variable is rarely needed just to reach a second field: {%alb|append(%per)} and {folder_album(>)|append({person})} do the same thing.

Escaping

A backslash makes the next character ordinary text. This is a Zouti Photos extension — osxphotos has no escape character, so use the literal-character fields instead if the template has to work in both.

Escapable: { } \ , ? & | + ( ) [ ] and a space. A backslash before anything else is just a backslash, so a Windows-style path in a template is left alone.

It works anywhere text is expected: defaults, filter arguments, find/replace pairs, field arguments, and format codes. {keyword|join(\,)} joins with commas; {counter:\,d} writes 1,234 rather than 1234.

The graphical builder cannot draw escapes — a template containing one stays text-only.

Format codes

A Python format code after a colon pads or formats any field’s value. These follow Python’s format specification mini-language, which is the place to look for the full set of options:

[[fill]align][sign][#][0][width][grouping][.precision][type]

Alignments are < > ^ =; types are d b o x X f F e E g G % s. With no type, a value that looks like an integer is formatted as one when the spec asks for numeric padding, and as a string otherwise. Zouti Photos implements a practical subset — the pieces that make sense for the string values a template field produces.

The grouping option needs the escape — a bare comma would start the default slot first. Grouping applies to integers only.

To convert before formatting, use {format:TYPE:CODE,TEMPLATE}.

The order things happen in

When several parts appear on one field, this is the order they are applied — worth knowing when a template does not do what it looks like it should:

the field produces a list of values
          ↓
[find,replace]     text replaced inside each value
          ↓
delim+             the list joined into a single value
          ↓
|filters           left to right, each on the last result
          ↓
&more              another template's values added
          ↓
test / ?yes / ,no  what actually gets written

Field reference

Dates

Four date sources: created (when the photo was taken), added (when it was imported), modified (when it was last changed), and today (the date the template runs — a property of the export, not of the photo).

added and modified fall back to the capture date when the library recorded none.

Follow any source with a component. Bare {created} is the same as {created.date}.

{modified.date} → 2026-05-02. {today.date} → the day you run the export.

Custom date formats

{created.strftime,PATTERN} formats the date with a strftime pattern given in the comma slot. This strftime reference is a handy place to look up the codes and see them previewed.

Because the pattern occupies the comma slot, a .strftime field takes no default.

Dates render in the time zone the export is configured to use, so {created.hour} answers the question you are actually asking rather than reporting the photo’s instant in your Mac’s zone.

Names and identity

{current_name} is another spelling of {name}.

Export appends the real extension itself, so the *_name forms are the right ones for a filename template and the *_filename forms are for folder names and other text.

{img_number} is deliberately strict. The original name must be IMG_ followed by exactly four digits, so IMG_E1234, IMG_12345, DSC_1234 and MyPhoto2025 all render nothing at all. That is what makes it useful with a fallback: {img_number,{original_name}} numbers the photos that came from a camera and keeps the original name for everything else.

Counters

{counter} is a sequential counter over the photos in the current run, starting at 1. {counter.a}, {counter.b} and so on are independently configured counters.

{counter(start,stop,step)} configures it. stop is never reached — the counter resets to start when it would pass it.

At position 7 of a run:

A counter always derives from the photo’s position, so re-rendering a photo never changes its number — a preview shows the same value the export will write.

What you typed

{keywords}, {albums} and {persons} are accepted as plural spellings of the same fields.

An album not inside a folder renders identically as {album} and {folder_album}.

What Photos recognized

These come from the Photos search index, so they are empty for photos Photos has not analyzed yet. Machine-generated — unlike {keyword}, which is what you typed.

{labels} is accepted as a plural spelling of {label}.

Location

Two families, and they are not the same thing. {place.address.…} are the postal fields. {place.name.…} are what the map service named that level of the hierarchy, which is not always the postal spelling; each falls back to the matching postal field when Photos recorded no name.

Alternative spellings, all resolving to the field above: {place.city}, {place.address.state_province}, {place.state_province}, {place.address.country}.

Every one of these renders a single value. Photos can store several names at one level; the first is taken, because a multi-value {place.name.city} would silently export one copy of the photo per alternate spelling.

Camera

Also spelled {camera_make}, {camera_model}, {lens_model}.

Where it came from

{imported_by.name} is another spelling of {imported_by}.

Status

{hdr}, {favorite}, {hidden} and {edited} are true/false. A true one renders the literal True; a false one counts as no value and takes the default — which is why these fields are almost always written as a question.

{edited} means “an edited version of this photo exports”, which is slightly wider than “the user edited it”: a capture-time slow-motion movie still exports a retimed rendition.

Media types

{media_type} reports the most specific type Photos recorded, testing in this order and taking the first that fits. {photo_or_video} answers only the two-way question.

Because these fields always have a value, their comma slot is put to a different use: it renames types rather than supplying a default.

{media_type,video=movie;slow_mo=slowmo}

writes movie and slowmo and leaves every other type alone. Only the names in the table may appear on the left, and each needs a replacement — a comma slot that is not a list of type=name pairs is an error, rather than a default that could never fire.

Photo properties

{photo.…} reaches the scalar properties of Zouti Photos’s own metadata record. Bare {photo} is the UUID. Dates here are ISO 8601. A true/false property behaves like {favorite}: false counts as no value, so it takes the default.

{photo.width}x{photo.height} → 4032x3024.

Records and lists are deliberately left out — use the album, keyword, person, location and camera fields for those. An unknown or non-scalar property name is an error.

Transforming another template

Three fields take a template in the comma slot and transform whatever it renders. Because that slot is the argument, these fields never take a default.

TYPE is int, float or str; CODE is a format code. int goes through a float first, so a value of 3.7 can be formatted as an integer instead of erroring.

The argument keeps its whole value list, so {shell_quote,{keyword}} quotes each keyword rather than collapsing them: 'Travel' + 'Vacation' + 'Beach'.

More examples: {format:float:.2f,3.14159} → 3.14; {format:str:>20,{title}} → Sunset over the bay.

Literal characters

A comma, brace or parenthesis would otherwise be read as part of the syntax, so each has a field of its own. A backslash escape reaches the same characters more briefly, but these spellings are what osxphotos templates use and are the portable choice.

osxphotos spells three of them differently and both spellings work here: {questionmark}, {openparens}, {closeparens}.

Filter reference

Text filters

Applied to each value in the list.

chop and chomp default to 1 character. zfill keeps a leading sign ahead of the padding, so -1 becomes -001.

sslice takes Python’s start:stop:step, so bounds may be negative and a negative step counts backwards:

List filters

Applied to the list as a whole.

|split defaults to splitting on a space. |slice(::-1) reverses the list.

append, prepend and remove take a list. Their argument may be a template, and every value it renders is used — or none, if it renders nothing:

Every other filter needs its argument to come to exactly one value.

Cookbook

Export folders

The album and person templates above are multi-value: a photo in two albums is exported into both. That is usually the point of them.

Export filenames

|join on a photo with no keywords produces one empty value, which in an export name becomes _ — {original_name}-{keyword|sort|join(_)} renders IMG_9876-_. The trailing , in the recipe above is an explicitly empty default, which renders IMG_9876- instead.

Sidecar keywords

The keyword template turns every rendered value into one keyword, so multi-value is what you want here.

Bulk Edit

Remember that a blank rendered value means “leave this photo alone”, so {title,} is a safe no-op rather than a mass clear.

Errors

An unknown field, filter, photo property or variable name is an error rather than an empty result, so a mistyped template never quietly writes a misleading name.

Errors that depend only on the template — a misspelled field, an unknown filter, a malformed slice — are reported as you type. Errors that depend on a value — {format:int:03d,{title}} on a photo whose title is not a number — are reported per photo when the template runs.

Whatever you are writing a template for, preview it before committing to it. The export window’s Preview plans every name without writing a file, and Bulk Edit’s table shows the exact value each photo would receive. Both are the quickest way to see multi-value expansion, defaults that fired, and results you did not intend.

Limits

Templates are user input, and a short one can ask for an unbounded amount of work. Three limits keep a mistake to an error message rather than a hung app:

Differences from osxphotos

Zouti Photos implements the useful core of the osxphotos metadata template language, and templates written for one usually work in the other, but it is not a drop-in replacement.

Not implemented

• {function:…}, |function:… and {exiftool:…} do not exist here. A sandboxed app cannot run external code, and Zouti Photos has no dependency on exiftool.
• {detected_text} reads what Photos already detected rather than running text detection, so it takes no confidence threshold.

Different

• {photo.…} follows Zouti Photos’s own metadata record, so its property names are not the osxphotos PhotoInfo names.
• {counter} starts at 1 rather than 0 — use {counter(0)} for the old behavior — and always derives from the photo’s position rather than from how many times it has been evaluated, so re-rendering never changes a number. {id} is that position rather than a database key.
• An unknown field, filter, property or variable is an error rather than an empty result. The same goes for a misspelled date component, a malformed slice, and a {media_type} rename list that is not one.
• A + after the field name no longer starts a join. osxphotos scans the whole {…} for the last +, so {title,a+b} there means “join with title,a” — almost never what was meant. Here a field name followed by any of : ( | [ & ? , or a space rules the join out. The cost is that a join delimiter containing one of those characters needs an escape: {a\ b+keyword}.

Additions

• Backslash escaping. osxphotos has no escape character at all; the {comma}-style fields are the portable spelling.
• A filter argument may be a template. {keyword|append({person})} works here and is literal text there.
• append, prepend and remove take a list, not just a single value.
• Format codes work on every field, not only the numeric ones.
• zfill and {space} are additions, as are {semicolon}, {ampersand}, {openbracket} and {closebracket}.

The example photo

Every rendered value on this page comes from one photo:

Where an example says (photo with no title) or similar, it was rendered against a second photo carrying nothing but a filename (IMG_9876.JPG) and the same capture date.