What is a “PhotoStructure library”?

September 6, 2020

Your PhotoStructure library contains

📚 your image database,
⚙️ library settings,
🖼️ preview images, and
🎞️ transcoded videos (if enabled).

These files are created when PhotoStructure imports your photos and videos, and enable PhotoStructure’s fast and fun user interface.

If you opt into automatic organization, your library will also contain your original photos and videos.

How much disk space does a library take? 🔗

You can store your library on either a local or network filesystem.

You’ll need roughly two gigabytes of extra disk space per thousand images in your library to store preview images.

For more details, read “how much disk space do I need for my library?”

Can I open my library on other computers? 🔗

Yes! PhotoStructure libraries are designed to be portable across computers and even across platforms.

Caveats 🔗

Running PhotoStructure on multiple computers has a couple caveats:

A PhotoStructure library can only be opened by one computer at a time. Shut down on one computer before you start on another computer. If you do this accidentally, PhotoStructure will display an error message telling you which computer still has your library open.
If you want your library to be portable, PhotoStructure needs to write a small file to the root directory of all the volumes that contain photos and videos. Read more about volumes and these .uuid files.

Importing from different computers 🔗

If your photos and videos are scattered across several computers, or you have a much faster desktop than your NAS, PhotoStructure gives you the flexibility of running imports whereever is most convenient for you.

If you put your PhotoStructure library either on an external hard drive or on your NAS, you can move your library as you see fit.

We’ve found this convenient especially if you have a slow NAS and a fast desktop: the initial import can run on your fast desktop, using a NAS share to store the library. The fast desktop does the “heavy lifting” of the import, and then your NAS can do the easy job of running the web service and incremental syncs.

Can I move my original photos and videos after they are imported? 🔗

Yes, but the new location of your files won’t be shown in your library until PhotoStructure runs a “sync.” You can manually start a sync via PhotoStructure’s ☰ navigation menu.

I’ve edited a photo and the change isn’t showing up in my library. 🔗

PhotoStructure automatically synchronizes your library with what it finds on your filesystem, and assumes other programs may change things around.

As you browse your assets, if you click the “info” panel, and PhotoStructure sees that it is out sync with any files, it will automatically-resync the files for that asset. You can also force this operation by selecting the Resync this asset menu option while viewing an asset.

Where are my library’s database, settings, sync reports, and preview files? 🔗

These are all stored in a hidden .photostructure directory. Navigate to your PhotoStructure library, and look for that directory.

On macOS, hit ⌘-shift-. (command-shift-period) to show hidden files within Finder.

On Windows, click View > Hidden Items within the Explorer window.

On Ubuntu’s gnome browser, click the ☰ menu icon in the title bar, and select Show Hidden Files.

Caution: moving or deleting files in this directory, other than your library settings, may prevent your library to open, or cause errors while browsing your library.

If I import photos and videos from an external drive, and then eject it, what happens? 🔗

If you enabled “automatic organization:” 🔗

A copy of all original photos and videos will also be in your PhotoStructure library, so those assets will work as expected.

If you did not enable “automatic organization:” 🔗

Thumbnails for those photos and videos will still live in your PhotoStructure library
Clicking on images should show a preview. Zooming into the image will be limited, as your library only contains a reduced-resolution preview.
Clicking on videos may work, if the video was transcoded into your library because the original video format wasn’t natively supported by most modern browsers.

If you plug the drive in again, later 🔗

PhotoStructure should automatically start a sync job for that volume. If PhotoStructure was able to find a volume UUID for the disk, the sync should complete fairly quickly, and only pick up any changes made since the last sync.

If any files were deleted from the volume, and “automatic organization” is disabled, the asset for that file will be removed from your library.

When does PhotoStructure remove assets from your library? 🔗

PhotoStructure only removes assets from your library when:

the volume it found the asset file in is currently mounted, and
a parent directory exists, and
the file is missing, and
it was the only asset file “variant” for the asset