Why didn't my file get imported into my Library?

PhotoStructure has a number of filters that all must pass for a photo or video to be added to your library.

Directory filters đź”—

PhotoStructure doesn’t import any files from system directories, hidden directories, or NoMedia directories.

File filters đź”—

  1. The file must be a JPEG, PNG, digital camera raw format, or a video format that FFmpeg can decode.

  2. If the JPEG is found to be corrupt it will be skipped. This may be due to bitrot or file truncation due to a failed backup.

  3. If the image is too small, it will be skipped. The default minimum dimension is 480 pixels for images, and 240 pixels for videos. The default minimum filesize is 50 KB. These defaults can be changed with the minImageDimension, minVideoDimension, and minAssetFileSizeBytes library settings, or the PS_MIN_IMAGE_DIMENSION, PS_MIN_VIDEO_DIMENSION, and PS_MIN_ASSET_SIZE_BYTES environment variables.

  4. If a file is too large, it will be skipped. This mostly applies to videos, and prevents your NAS from filling up with transcoded versions of that 45 minute piano recital that you’ll never watch. This defaults to 500 MB, and can be changed with the maxAssetFileSizeBytes library setting.

  5. PhotoStructure will refuse to walk into directories that have the same path element more than 7 times. This helps avoid getting stuck in infinite filesystem loops caused by symbolic links.

  6. PhotoStructure doesn’t currently support HEIC/HEIF format out of the box due to licensing. (Please tell Apple not to use a closed, patent-encumbered format for something as important as your photos!)

    If you’re willing to use PhotoStructure for Servers, though, you can compile that support for yourself. This method does require some level of comfort with the terminal.

Why didn’t an individual file get imported? đź”—

There are a couple of ways to see why PhotoStructure didn’t import something:

Via sync reports đź”—

PhotoStructure v2.1 (as of July 2022, is currently in alpha) writes “sync reports”. More details are here.

Via command-line tools đź”—

If you’re comfortable with the terminal, use PhotoStructure’s info and list command-line tools.

New excludeGlobs setting đź”—

Version 2.1 adds a new way to exclude directory and file name patterns from your library.

Photo of Matthew

Hi! I’m Matthew, the author of PhotoStructure. I’m a dad, amateur photographer, and author of open source, adtech, fintech, and edtech software since the turn of the millennium. He/him. I am building a self-hosted, safe, and fast new home for all your photos and videos.
Your memories deserve PhotoStructure. Try it out for free!