How PhotoStructure stores file locations

How PhotoStructure stores file locations

PhotoStructure stores each imported file’s location as a URI (uniform resource identifier): a structured address such as psfile://3DNCoKQz4/Pictures/image.jpg. The pslib:, psfile:, and psnet: schemes provide something more durable than a Windows drive letter or a macOS, Linux, or Docker mount path, all of which can change without the file moving on its storage device.

You normally won’t need to work with these values directly. You may see them in command output, logs, or the library database, though, and the scheme at the start tells you how PhotoStructure will find the file again.

SchemeExampleWhat it identifies
pslib:pslib:/2026/08/image.jpgA path under the current library or originals directory
psfile:psfile://3DNCoKQz4/Pictures/image.jpgA path relative to a volume with a stable identity
psnet:psnet://nas.example/family/2026/08/image.jpgA path relative to a network host and share
file:file:///Users/alice/Pictures/image.jpgAn absolute path, used when PhotoStructure can’t build a URI listed above

URIs encode characters that have a special meaning in an address. For example, Family Trip.jpg appears as Family%20Trip.jpg. PhotoStructure decodes the URI before accessing the file; the filename on disk does not change.

How PhotoStructure chooses a URI

For a given native path, PhotoStructure tries these forms in order:

  1. pslib: when the file is under the configured originals or library directory
  2. psfile: when the containing volume has a stable identity
  3. psnet: when the file is on a network share with a known host and share
  4. file: as an absolute-path fallback

A file on a NAS may therefore use a psfile: URI when its mounted volume has a usable identity. PhotoStructure uses psnet: when it can identify the network host and share but cannot build a stable volume-relative URI.

PhotoStructure may also compare several valid URIs for the same file while matching database records. For example, a volume can retain older identities as aliases. The order above determines the preferred URI; the alternatives help PhotoStructure recognize a file it has already catalogued.

pslib: library-relative paths

A pslib: URI contains a path relative to PhotoStructure’s configured asset directories:

pslib:/2000/2000-01-01/image.jpg

Unlike the other PhotoStructure schemes, pslib: has no authority between the colon and path, so its usual spelling has one slash rather than two.

PhotoStructure first looks for the relative path under the configured originalsDir, then under libraryDir. If the file exists under neither, the resolved path falls under originalsDir. Storing the same relative path under both directories is unsupported; the copy under originalsDir wins.

Because the URI does not contain either directory’s native path, the library and originals directories can use different paths on another computer. The libraryDir and originalsDir settings tell that computer where to resolve the URI.

psfile:// volume-relative paths

A psfile:// URI contains a compact volume ID followed by a path relative to that volume’s root:

psfile://3DNCoKQz4/Pictures/image.jpg

Here, 3DNCoKQz4 is derived from the volume’s identity. It is not a drive letter, volume label, or mount path. PhotoStructure looks up the volume’s current mount point before accessing the file, so the URI can survive changes such as F:\ becoming G:\ or /Volumes/Photos becoming /Volumes/Photos 1.

When several mount points share the same volume ID, PhotoStructure prefers one where the file exists. If the file exists under none or more than one, it uses the shortest, root-most mount point.

See What’s a volume? for how PhotoStructure chooses volume identities, handles identity aliases, and uses .uuid files when the storage device does not provide a suitable UUID.

psnet:// network-share paths

A psnet:// URI contains a host, a share name, and the path within that share:

psnet://nas.example/family/2026/08/image.jpg

In this example, nas.example is the host and family is the share. PhotoStructure matches those values to a currently mounted network volume on macOS and Linux. On Windows, it can also resolve the URI as a UNC path such as \\nas.example\family\2026\08\image.jpg.

The host and share take the place of the compact volume ID used by psfile://. This makes psnet:// useful for network filesystems that do not expose a stable volume UUID and whose root does not contain a readable .uuid file.

file: absolute-path fallback

An ordinary file: URI records the absolute native path. PhotoStructure uses it only when it cannot create a pslib:, psfile:, or psnet: URI. Because the path depends on one computer’s operating system and mount layout, this is the least portable form.

When the storage is unavailable

A stored URI identifies where a file belongs; it does not prove that the file is accessible right now. An ejected disk or unmounted network share can leave a URI temporarily unresolved, or PhotoStructure may display the last known native path even though no file exists there. Neither condition by itself means the file was deleted.

When the volume or share returns with the same identity, PhotoStructure can resolve the stored URI again. This distinction lets the library keep records for files on storage that is only connected occasionally.

See also