What's a "volume?"
During setup, PhotoStructure asks where to find your photos and videos — these are your scan paths. But how does PhotoStructure keep track of which drive is which, especially when drive letters and mount points can change?
That’s where volumes come in. PhotoStructure uses the word “volume” to mean any storage location available to your computer.
This includes:
- The internal storage 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 physical drives in a RAID
- A Docker bind mount from a host directory into the container
A single volume may use part of one disk, or span several disks.
🐳 Docker and volumes
In Docker, your photos and videos are made available through bind mounts – host directories mapped into the container. PhotoStructure sees each bind mount as a separate volume.
Docker containers can’t access host volume UUIDs, so PhotoStructure relies on .uuid files instead. See the Docker setup guide and Docker Compose wizard for details.
💽 Why does PhotoStructure need to know about volumes?
PhotoStructure needs a stable way to refer to your photos and videos.
Say you plug two external drives into a Mac. They mount as /Volumes/Untitled and /Volumes/Untitled 1. Reboot, and macOS may swap which drive gets which name.
Without a stable identifier, PhotoStructure would see these swapped mount points as new volumes and re-import everything – doubling your library’s database size for no reason. The files would all be deduplicated, but larger databases consume more RAM and are slower.
This isn’t just a Mac problem: Windows can reassign drive letters, and Linux uses similar mounting heuristics.
🤔 How PhotoStructure identifies volumes
Your library needs to work across different computers and operating systems, so PhotoStructure can’t rely on drive letters or mount paths – those are OS-specific and can change.
Instead, PhotoStructure uses volume UUIDs: unique identifiers that each operating system assigns to storage volumes. These stay the same regardless of where or how the volume is mounted.
PhotoStructure shortens the UUID into a compact ID like 3DNCoKQz4, and uses it in your library database: psfile://3DNCoKQz4/Pictures/image.jpg. This URI stays stable even if the drive letter or mount point changes.
💔 When volume UUIDs aren’t available
Volume UUIDs aren’t always accessible – Docker bind mounts, network shares (NAS), and some cheap USB drives don’t provide them.
🪛 The .uuid file workaround
To handle these cases, PhotoStructure looks for a .uuid text file in a volume’s root directory. If one exists, its contents are used as the volume’s identifier.
If no .uuid file exists, PhotoStructure tries to read the OS-level volume UUID. If that also fails, it generates a new random UUID and writes a .uuid file.
A .uuid file always takes priority over the OS-level volume UUID.
If PhotoStructure doesn’t have write access to the volume root (common with Docker and NAS setups), you can create the .uuid file yourself.
✍️ How to manually add .uuid files
Set $VOLUME_MOUNTPOINT to the root of the volume, then run the appropriate command for your OS.
On Linux or macOS:
uuidgen | sudo tee $VOLUME_MOUNTPOINT/.uuid
sudo chmod ugo+r $VOLUME_MOUNTPOINT/.uuid
On Windows (PowerShell) – replace F: with the correct drive letter:
New-Guid | Select-Object -ExpandProperty Guid | Out-File -NoClobber -FilePath F:\.uuid
The UUID doesn’t need to match any hardware ID – it just needs to be unique.
🏗️ If you add or change a .uuid
PhotoStructure assumes volume UUIDs don’t change. If you add or modify a .uuid file, you’ll need to rebuild your library via the system menu. You can start a rebuild while an import is running.
🦄 UUIDs must be unique!
If you clone a disk with a .uuid file, write a new .uuid on the clone. Two devices sharing the same UUID will confuse PhotoStructure – it will treat them as one device, and the last-scanned volume’s metadata will overwrite the other’s.
Your photos and videos won’t be altered, but your library database will only reflect the last-scanned volume.
😐 Volume UUIDs don’t fix everything
Volume UUIDs prevent duplicates when the same directory is mounted at different paths or on different computers. But they can’t help if you mount a subdirectory of a volume separately.
For example, a NAS might expose both \\server\home and \\server\homes\username, which point to the same directory. PhotoStructure will import both, doubling your asset file count (though the assets themselves are still deduplicated). See “Library Metrics” for more details.
🙅 Disabling .uuid writing
PhotoStructure won’t write .uuid files to volumes with a NoMedia file or folder in their root directory.
To disable .uuid writing entirely, set the environment variable PS_WRITE_VOLUME_UUID_FILES=false.
