Skip to content
Frameleaf Docs

Storage template

By default Frameleaf stores each upload under a folder for its owner, with a name that has nothing to do with the photo. The storage template lets you choose a readable layout instead, such as one folder per year and day, or one folder per album. It only changes where files sit on disk. Your library in Frameleaf looks the same either way.

Find it in Settings, then Storage & originals, then Originals & folder structure.

Where files go

Section titled “Where files go”
Template Originals are stored in
Off (default) upload/<account ID>/…, with generated names
On library/<account ID or storage label>/<your template>

Both folders are inside your UPLOAD_LOCATION. Each person’s folder uses their storage label if they have one, otherwise their account ID.

Backup and restore explains which folders hold what, and why your backups need both the database and the files either way.

Turn it on

Section titled “Turn it on”
  1. Open Settings, then Storage & originals, then Originals & folder structure.
  2. Turn on Enable storage template engine. Leave Hash verification enabled on unless you’re certain of the implications.
  3. Choose a Preset, or type your own Template using the variables below. The Preview shows the path a sample photo would get, with an approximate path length.
  4. Select Review changes, then Save changes.

Template changes only apply to new uploads. To move what’s already there, run the Storage Template Migration job from Compute & jobs, then Job manager. You can run it again whenever you change the template, so you’re never stuck with a layout.

The default template is:

{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}

which stores a photo taken on 31 December 2025 as 2025/2025-12-31/IMG_123.jpg.

Variables

Section titled “Variables”

Date and time variables use the photo’s creation time, shown in the server’s time zone (TZ).

Kind Variables
Year {{y}} (2025), {{yy}} (25)
Month {{M}}, {{MM}}, {{MMM}}, {{MMMM}} (12, 12, Dec, December)
Week {{W}}, {{WW}}
Day {{d}}, {{dd}}
Hour {{h}}, {{hh}}, {{H}}, {{HH}}
Minute {{m}}, {{mm}}
Second {{s}}, {{ss}}, {{SSS}}
File name {{filename}} (IMG_123), {{ext}} (jpg)
File type {{filetype}} (IMG or VID), {{filetypefull}} (IMAGE or VIDEO)
Camera {{make}}, {{model}}, {{lensModel}}
Album {{album}}, {{album-startDate-x}}, {{album-endDate-x}}, where x is a date variable such as y or MM
Other {{assetId}}, {{assetIdShort}} (last 12 characters of the ID)

Extensions are always made lowercase. If two files would end up with the same name, a number is added so nothing is overwritten.

Presets

Section titled “Presets”

The template builder offers these presets, among others:

Preset Example result
{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}} 2025/2025-12-31/IMG_123.jpg
{{y}}/{{MM}}/{{filename}} 2025/12/IMG_123.jpg
{{y}}/{{MMMM}}/{{dd}}/{{filename}} 2025/December/31/IMG_123.jpg
{{y}}/{{y}}-{{WW}}/{{filename}} One folder per week
{{album}}/{{filename}} One folder per album
{{make}}/{{model}}/{{lensModel}}/{{filename}} One folder per camera and lens
{{y}}/{{y}}-{{MM}}-{{dd}}/{{assetId}} Named by asset ID instead of the original name

Albums in the template

Section titled “Albums in the template”

If a photo is in several albums, {{album}} uses the album that was created most recently.

Special characters in album names are turned into HTML entities by default, so & becomes &amp;. To keep them as they are, use three braces: {{{album}}}.

To use album folders but still give photos outside any album a home, use {{#if album}}, {{else}} and {{/if}}. This stores album photos in the album’s folder and everything else in Other/<month>:

{{y}}/{{#if album}}{{album}}{{else}}Other/{{MM}}{{/if}}/{{filename}}

And this files albums under the year the album starts:

{{#if album}}{{album-startDate-y}}/{{album}}{{else}}{{y}}/Other/{{MM}}{{/if}}/{{filename}}

Things to know

Section titled “Things to know”
  • External libraries aren’t moved. The template only applies to files Frameleaf stores itself. Files in external libraries stay where they are.
  • Live Photos stay together. The video part of a Live Photo is moved alongside its still.
  • Storage labels don’t move files on their own. After changing someone’s label, run the migration job.
  • Folder view shows the result as a folder tree, which works well with a tidy template. Turn it on in Settings, then Your preferences, then Library features, then Enable folders.
  • The same page also holds the physical deduplication switch, because shared files follow the master account’s layout.