Hybrid PhotoStructure libraries

PhotoStructure offers a lot of flexibility with how you lay out your photos and videos.

Initial library setup

When you’re initially setting up PhotoStructure, you can set up the following:

  1. You can put your library directory on either a local or remote filesystem

    (if you’re on Windows, though, map your network drive to a letter first: heavy disk I/O against UNC paths can be flaky)

  2. You can choose to leave your existing photos and videos where they are already, or automatically organize them into your library

  3. You can scan any number of directories that are outside your library. Here’s a screenshot of the “scan paths” card in PhotoStructure’s settings page:

Performance with larger libraries

If you have a larger library, you may want more flexibility in how your library is stored.

Note that the following approach requires configuring advanced settings, and comfort with the terminal is recommended.

HDD versus SDD speeds

PhotoStructure is designed to make browsing as fast as possible: it’s just not fun to browse your library if every click takes a couple seconds.

PhotoStructure does this by “front-loading” as much work (like image preview generation and video transcoding) during asset importing and syncing, but we still need reasonably fast disk I/O to serve pages.

As an example, on my 4k display and using tiny thumbnails (which should be a worst-case scenario), here’s my library’s home page

Loading this page required ~500 requests for images (as it’s also lazy-loading the next page or 2 of images).

For my test library stored on SSD, this loads in ~1 second.

For my test library stored on an HDD (5400 RPM RAID-1), this page takes ~7-10 seconds for all the images to slowly stream in.

If you can store your preview directory on an SSD, that really helps.

How do I get faster library browsing performance?

SSDs are the answer! Large capacity SSDs are now ~$100 per TB.

If your library and all your original photos and videos can be stored on SSD, this is highly recommended: it’s just simpler to set up and use.

If this doesn’t work for your library, though, and you still want faster library performance, you may want to adopt a “hybrid” approach where you store your original files on a separate volume from your preview files.

Hybrid libraries

One of PhotoStructure’s unique features is “portable” libraries: if you move or mount your library directory on a different computer, it’ll open right up and let you add new assets from that different computer.

Hybrid libraries, where you store your original files on a separate volume from your preview files, aren’t as seamlessly portable, though: you have to manually set PS_LIBRARY_DIR and PS_ORIGINALS_DIR to open your library (and retain access to your originals).

It’s up to you to decide if this complexity and inconvenience is worth it!

Initial hybrid library setup

If you’re just starting out:

  1. Find an HDD with enough storage to store your original photos and videos. Set the PS_ORIGINALS_DIR environment variable to the full pathname to this directory.

  2. Install PhotoStructure, and choose your SSD to be your library directory in the Settings page. Note that your PS_ORIGINALS_DIR value won’t be shown in the settings UI (but it will in future PhotoStructure builds).

  3. You’re done: PhotoStructure will use PS_ORIGINALS_DIR to store original photos and videos instead of your library directory.

Converting an existing library to a hybrid library

If you already have a PhotoStructure library (in this example, stored at /mnt/hdd/ps-library), and a new SSD (in this example, stored at /mnt/ssd/):

  1. Shut down PhotoStructure

  2. Move /mnt/hdd/ps-library/.photostructure to /mnt/ssd/ps-library/.photostructure (this may take a while if your library is large!)

  3. Set PS_LIBRARY_DIR=/mnt/ssd/ps-library

  4. Set PS_ORIGINALS_DIR=/mnt/hdd/ps-library

  5. Restart PhotoStructure.


You may notice PS_PREVIEWS_DIR in your system settings: this was an initial attempt to build out support for hybrid libraries.

By using PS_ORIGINALS_DIR, your library remains “intact”: the database and previews sit next to each other, and at least your tag galleries will render properly if you don’t set PS_ORIGINALS_DIR properly.

With PS_PREVIEWS_DIR, your library is fractured into multiple places, and won’t even open if PS_PREVIEWS_DIR and PS_LIBRARY_DIR aren’t set correctly.

If you get PS_ORIGINALS_DIR wrong, you just break full-screen asset zooms and playback of your non-transcoded videos.

Due to this added bit of complexity, we recommend using PS_ORIGINALS_DIR instead.



Using a “hybrid” library is completely optional, and really should only be taken on if you’re suffering from really poor performance.

If possible, try to keep things simple!