# Import from a folder or another app

Source: https://frameleaf.app/docs/migrate/from-a-folder/

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](#upload-from-your-browser) | Files are copied into Frameleaf's storage. | A few folders, with nothing to install. | Anyone |
| [Copy with Frameleaf Desktop](#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](#upload-folders-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](#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](https://frameleaf.app/docs/migrate/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](https://frameleaf.app/docs/migrate/icloud-photos/). To bring a whole library across from another photo app, with its accounts and albums, see [Bring an existing library](https://frameleaf.app/docs/migrate/from-another-library/). To move a whole library from one Frameleaf server to another, see [Move to a new server](https://frameleaf.app/docs/admin/move-to-a-new-server/).

## 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](https://frameleaf.app/docs/using/uploads-and-downloads/).

## Copy with Frameleaf Desktop

[Frameleaf Desktop](https://frameleaf.app/docs/apps/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](https://frameleaf.app/docs/apps/desktop/#bring-in-a-photo-folder).

## 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](https://frameleaf.app/docs/admin/api-and-cli/).

### Install it

Install the CLI by following [API and CLI](https://frameleaf.app/docs/admin/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

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](https://frameleaf.app/docs/using/account-settings/#api-keys).

### Sign in

```bash
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.

### Upload

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

```bash
frameleaf upload --dry-run --recursive ~/Pictures/Archive
```

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

```bash
frameleaf upload --recursive --album ~/Pictures/Archive
```

More examples:

```bash
# 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
```

### 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 |

:::danger
`--delete` and `--delete-duplicates` remove files from your computer or drive. Use them only after you've made a backup and checked the upload with a dry run.
:::

:::tip
Use `--visibility locked` to send private photos straight into [Locked](https://frameleaf.app/docs/using/private-content/).
:::

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

## 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.)

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](https://frameleaf.app/docs/admin/external-libraries/) for every option. To try Frameleaf on photos another app looks after, see [Try Frameleaf without moving your photos](https://frameleaf.app/docs/migrate/try-without-moving-your-photos/).

:::note[The Imports folder is something else]
Every server also has a built-in **Imports** folder, the `imports` folder inside Frameleaf's storage folder. It's a place to drop an export, such as a Google Photos Takeout, so an import can read it without uploading. Nothing in it joins your library until you import it. See [Import from a folder on this server](https://frameleaf.app/docs/migrate/google-photos/#advanced-import-from-a-folder-on-this-server).
:::

## 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](https://frameleaf.app/docs/using/library-care/#live-photos).
- **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](https://frameleaf.app/docs/using/duplicates/) helps you find them and keep the best copy.
- **Fix dates.** Scans and old exports often carry the wrong date. [Date & Time Doctor](https://frameleaf.app/docs/using/date-and-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](https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/using/damaged-and-missing-files/#uploading-or-importing-the-photo-again).
