When you set up your library, you’ll see this option:
PhotoStructure uses the words “disk,” “drive,” and “volume” to mean any storage device available to your computer.
- The internal hard drive of your laptop or desktop
- An external USB hard drive or thumb drive
- An SD card in a built-in or external card reader
- A shared network directory from your NAS, possibly spanning several drives in a RAID.
For the more precise—nay, pedantic—readers: technically, disks are physical data storage, and volumes are logical storage. Single volumes may use just a portion of one disk, or partitions across several disks.
Just like macOS users are used to the term “folder,” and Windows users use the
term “directory,” these terms have been muddied as well. Windows users are used
to mounting “disks” to “drive letters”. MacOS mounts to
PhotoStructure is cross-platform, no term will be “native” to both sets of
fascinating. really. #
I’m getting to the good bit, hang on. It’ll be interesting, I swear.
Fine. Mildly interesting.
PhotoStructure needs a stable way to refer to the volumes you’ve mounted to your system.
If you plug in a new external hard drive into a Mac, it will mount to
If you plug in another new hard drive, or untitled SD card,
that will be mounted to
Reboot, or unplug and re-plug those devices, and which device gets
Untitled 1 is random, and can swap. Or be given
Why is that bad? #
Earlier versions of PhotoStructure would see these swapped volume mountpoints as new volumes, and re-import that volume. This could potentially double the size of your library’s database. The files would all be deduplicated, but larger databases consume more RAM, and are slower.
And Windows and Ubuntu users, don’t get smug: Windows is happy to give random drive letters to external devices, and Ubuntu uses similar mounting heuristics to macOS.
I smell a buildup to some clever solution… #
Old versions of PhotoStructure described files in your library database by using
the full pathname to your photo or video, so
D:\\Pictures\\image.jpg would be
We want PhotoStructure to provide the freedom to read and write your library on multiple computers, even when they’re different operating systems, or using PhotoStructure for Desktops or PhotoStructure for Servers. Your library shouldn’t be locked to an OS or hardware.
That portability requirement means that
/D:/ part of the URI isn’t going to
work (even if it was stable), because that drive letter is a windows-specific
thing. We need a better way to persistently identify volumes across operating
Volume UUIDs save the day… #
To get this persistent volume identifier, PhotoStructure asks the operating
system for the “logical volume UUID” of each volume. These looks something
PhotoStructure takes a short SHA of that UUID, like
3DNCoKQz4, instead of the
volume’s mountpoint or drive letter, to describe the file in your PhotoStructure
library database. The URI in your database then looks like
This solves both our problems: if the drive letter changes, the URI doesn’t change, and if you plug in that device into, say, your Mac or Linux box, we still get the same URI. 🎉
…except when they don’t #
Almost immediately after getting a shoulder cramp from the gosh-that’s-so-clever self-congratulations, our parade got rained out, because logical volume UUIDs aren’t always available.
Volumes exported into docker containers don’t have UUIDs.
Network filesystems (like an AFS or SMB mount from a NAS) don’t expose a UUID.
Some physical storage devices (like thumb drives and even some external hard drives) don’t have the hardware controller support that exposes a UUID.
The workaround… #
To work around this issue, PhotoStructure will use either the logical volume
UUID, or generate a new random UUID, and try to write it into a
file stored in the root directory of each volume.
This allows the volume to maintain a consistent UUID when mounted on a different device (which may not expose the UUID).
Note that the
.uuid file overrides the logical volume UUID.
If you’re using Docker, or importing files from a read-only device, like your
NAS, PhotoStructure may not have sufficient permissions to write to the root
directory to write this
How to manually add
.uuid files #
For volumes that you don’t want PhotoStructure to have write access to, you can create this file manually so your library can still get the benefit of stable URIs.
On Debian or Ubuntu:
# To set the uuid to match the hardware uuid, run `lsblk -P --output mountpoint,uuid`, # find the appropriate UUID, and cat the contents into $VOLUME_MOUNTPOINT/.uuid # Not all hardware devices have a UUID, though. In that case, run the following: # Install the `uuid` command: sudo apt install uuid # set $VOLUME_MOUNTPOINT to the volume you want to give a UUID to: sudo uuid -o $VOLUME_MOUNTPOINT/.uuid # Make sure PhotoStructure can read the contents: sudo chmod ugo+r $VOLUME_MOUNTPOINT/.uuid
On macOS (with homebrew):
brew install ossp-uuid # set $VOLUME_MOUNTPOINT to the volume you want to give a UUID to: sudo uuid -o $VOLUME_MOUNTPOINT/.uuid # Make sure PhotoStructure can read the contents: sudo chmod ugo+r $VOLUME_MOUNTPOINT/.uuid
On Windows, in PowerShell
# (replace `F:` with the proper drive letter): New-Guid | Select-Object -ExpandProperty Guid | Out-File -NoClobber -FilePath F:\.uuid # (There isn't a Set-Acl command here, as I'm assuming that the user you run # PhotoStructure with can already read the new .uuid file. If this isn't the case, # please add the read permission to this file.)
Note that this UUID doesn’t actually need to match the physical volume UUID. If
.uuid file in the root of a device, the file’s contents will be used
instead of the physical volume UUID.
🏗️ If you add or change a
PhotoStructure assumes that volume UUIDs are stable.
If you change the contents of a
.uuid or add a new
.uuid to a remote volume
rebuild your library, via the system navigation menu.
Read more about rebuilds here.
You can select
rebuild while an import is running: it will fix
currently-imported assets, and then continue with importing.
🦄 UUIDs must be unique! #
If you clone a disk that has a
.uuid file, make sure you write a different,
.uuid file to the cloned disk. Use the instructions above specific to your
If 2 different physical devices share the same
.uuid value, PhotoStructure
will assume they are the same physical device. If contents are different between
the devices, the last-scanned volume will “win” and library metadata for that
volume will overwrite the metadata from the other device.
Note that your photos and videos won’t be altered on either device, but your library database will only reflect the contents of the last-scanned volume with that UUID.
😐 Volume UUIDs don’t fix everything #
Volume UUIDs only address duplicates that arise from
- the same directory being mounted to different directories
- the same directory being mounted on different computers
PhotoStructure can’t detect if you mount a subdirectory of a volume: it will re-import the assets it finds in that subdirectory.
This situation isn’t theoretical: if you mount a remote SMB filesystem,
there will typically be two paths to your “home directory”:
In this situation, two URIs will point to the same directory. PhotoStructure
can’t detect this situation and will think that the contents of
\\nas\homes\alice are different directories and import both directories.
All assets from one volume will be marked as a duplicate of the other volume, so your asset count won’t increase, but your asset file count will double. (see “Library Metrics” for more details).
🙅 How do I disable
.uuid writing? #
Set the system
writeVolumeUuidFiles = false, or set the environment