Skip to content

Import from a folder or another app

Live Photo pairing: reconnect stills with their motion clips Watch on YouTube

Photos in folders on your computer, a NAS or an external drive, or exported from another photo app, come into Frameleaf easily. Pick the way that suits you:

What happens Best for Who can do it
Upload from your browser Files are copied into Frameleaf’s storage. A few folders, with nothing to install. Anyone
Copy with Frameleaf Desktop Files are copied into Frameleaf’s storage, and new ones follow. A folder on your computer that keeps changing, such as OneDrive. Anyone
Upload with the command line tool Files are copied into Frameleaf’s storage. A big one-off import, with an album for each folder. Anyone with an API key for their account
Connect a folder Frameleaf shows the files where they are, without copying them. An archive you want to keep managing yourself, such as a folder on your NAS. An administrator

Every way recognises a file you already have, so running an import again never adds a second copy.

For a Google Takeout export, use Import from Google Photos instead: it reads Google’s metadata files and brings your dates, descriptions and albums along. For an iPhone or iCloud library, use Import from iCloud Photos. To bring a whole library across from another photo app, with its accounts and albums, see Bring an existing library. To move a whole library from one Frameleaf server to another, see Move to a new server.

Choose Upload in the web app and pick files or a whole folder, with an album to put them in if you like. You can also drag files onto a library page. Keep the tab open until the upload finishes. See Uploads and downloads.

Frameleaf Desktop copies a photo folder from your Mac, Windows or Linux computer to your server, and can keep watching it for new photos. It also imports from a camera or memory card. See Bring in a photo folder.

The Frameleaf command line tool, frameleaf, uploads files and folders from any computer that can reach your server. It hashes each file first and skips anything already on the server, and Frameleaf recognises identical files on its side too, so you can run it again safely. This section covers bulk uploads; for everything else the tool does, see API and CLI.

Install the CLI by following API and CLI, using the package or container for your release. Keep its version in step with your server.

The examples below use the frameleaf command on your computer.

  1. Open Settings, then Your sign-in & privacy, then API keys.
  2. Select Create API key.
  3. Give the key a name and choose the permissions the tool needs.
  4. Create the key and copy it. It’s shown only once.

See API keys.

Terminal window
frameleaf login https://photos.example.com/api YOUR_API_KEY

Add /api to the end of your server address. The tool saves your credentials in auth.yml in ~/.config/frameleaf/ (or another folder you choose with -d or FRAMELEAF_CONFIG_DIR). Keep that file safe, and run frameleaf logout when you’ve finished.

Start with a dry run to see exactly what would be uploaded, without changing anything:

Terminal window
frameleaf upload --dry-run --recursive ~/Pictures/Archive

Then upload for real. This example includes subfolders and makes an album for each folder:

Terminal window
frameleaf upload --recursive --album ~/Pictures/Archive

More examples:

Terminal window
# Put everything into one album
frameleaf upload --recursive --album-name "Summer 2019" ~/Pictures/Summer
# Skip RAW folders and TIFF files
frameleaf upload --recursive --ignore '**/Raw/**' '**/*.tif' ~/Pictures/Archive
# Send everything straight to the archive
frameleaf upload --recursive --visibility archive ~/Pictures/Scans
# Keep watching a folder and upload new files as they appear
frameleaf upload --recursive --watch ~/Pictures/Inbox
Option What it does Default
-r, --recursive Includes subfolders. Off
-a, --album Creates an album for each folder, named after the folder. Off
-A, --album-name <name> Adds everything to one album. None
-i, --ignore <pattern> Skips files matching a glob pattern. You can give several. None
-H, --include-hidden Includes hidden files and folders. Off
--visibility <visibility> Sets visibility: archive, timeline, hidden or locked. Not set
-n, --dry-run Shows what would happen without uploading. Off
-c, --concurrency <number> Files uploaded at the same time. One less than your computer’s processor cores
--skip-hash Doesn’t hash files before uploading. Faster on a quick connection; the server still removes duplicates. Off
-j, --json-output Prints a JSON list of new files, duplicates and new photos. Off
--watch Keeps running and uploads new files as they appear. Off
--delete Deletes your local files after they upload. Off
--delete-duplicates Deletes local files that are already on the server. Off
--no-progress Hides the progress bars. Progress shown

Every option can also come from an environment variable, such as FRAMELEAF_RECURSIVE, FRAMELEAF_ALBUM_NAME or FRAMELEAF_UPLOAD_CONCURRENCY.

A connected folder leaves your files exactly where they are. Frameleaf shows its photos in someone’s library, beside their own uploads, and checks the folder again every night to pick up changes. Nothing is moved or copied, and Frameleaf doesn’t back the folder up. (Older guides call these external libraries.)

  1. Let Frameleaf see the folder. In Frameleaf Manager, add it under External folders. Frameleaf restarts for a moment. If you run your own Compose file, mount the folder into the server container.
  2. Add it in Frameleaf. Open Settings, then Libraries, and select Add a folder of photos. Choose the folder, whose library its photos appear in, what to skip, and whether the first check starts straight away. Then select Add folder.

Only folders connected to Frameleaf are listed when you choose one. If the list is empty, the window says Frameleaf can’t see any folders here yet and tells you to add yours under External folders in Frameleaf Manager. A folder you pick that isn’t connected says This folder isn’t connected to Frameleaf yet. Connect it, then choose it again.

See Folders of photos for every option. To try Frameleaf on photos another app looks after, see Try Frameleaf without moving your photos.

  • Rejoin Live Photos. If an export split Live Photos into a separate photo and video, open Settings, then Tools, then Live Photo pairing. It matches pairs on the identifier Apple embeds in both files, and suggests lower-confidence matches on file name and capture time for you to review. See Library care.
  • Tidy duplicates. Identical files are merged for you, with Undo. Imports from several sources often hold look-alikes too: resized or edited copies of the same picture. Duplicates helps you find them and keep the best copy.
  • Fix dates. Scans and old exports often carry the wrong date. Date & Time Doctor finds them and fixes them with an undo.
  • Let the background work finish. Frameleaf builds thumbnails, faces, search and descriptions after upload, and works on new arrivals before older background work. Big imports take a while; follow them in Activity.
  • Got back a photo you’d lost? When an import brings the original of a photo whose file was missing or damaged, Frameleaf puts it back under the photo you already have. See Damaged and missing files.