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.
Upload from your browser
Section titled “Upload from your browser”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.
Copy with Frameleaf Desktop
Section titled “Copy with Frameleaf Desktop”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.
Upload folders with the command line tool
Section titled “Upload folders with the command line tool”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 it
Section titled “Install it”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.
Create an API key
Section titled “Create an API key”- Open Settings, then Your sign-in & privacy, then API keys.
- Select Create API key.
- Give the key a name and choose the permissions the tool needs.
- Create the key and copy it. It’s shown only once.
See API keys.
Sign in
Section titled “Sign in”frameleaf login https://photos.example.com/api YOUR_API_KEYAdd /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.
Upload
Section titled “Upload”Start with a dry run to see exactly what would be uploaded, without changing anything:
frameleaf upload --dry-run --recursive ~/Pictures/ArchiveThen upload for real. This example includes subfolders and makes an album for each folder:
frameleaf upload --recursive --album ~/Pictures/ArchiveMore examples:
# Put everything into one albumframeleaf upload --recursive --album-name "Summer 2019" ~/Pictures/Summer
# Skip RAW folders and TIFF filesframeleaf upload --recursive --ignore '**/Raw/**' '**/*.tif' ~/Pictures/Archive
# Send everything straight to the archiveframeleaf upload --recursive --visibility archive ~/Pictures/Scans
# Keep watching a folder and upload new files as they appearframeleaf upload --recursive --watch ~/Pictures/InboxUpload options
Section titled “Upload options”| 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.
Connect a folder
Section titled “Connect a folder”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.)
- 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.
- 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.
After a big import
Section titled “After a big import”- 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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.



