Seamlessly Integrating Your Local Media into Immich: A Comprehensive Guide

Key Insights for Importing Local Media into Immich

Multiple Import Methods: Immich offers versatile import options, including the web interface for smaller uploads, external libraries for managing existing file structures, and powerful CLI tools (Immich CLI and Immich-Go) for bulk imports and advanced features like metadata handling.
Preserving Original Files: Immich prioritizes data integrity by not modifying original files during import. Instead, it creates companion files for metadata and transcoded versions, ensuring your source media remains untouched.
Optimized for Self-Hosting: Designed for self-hosted environments, Immich integrates well with Docker, allowing for flexible volume mounts and efficient management of large media collections directly on your server.

Immich stands out as a robust self-hosted solution for managing your cherished photos and videos, offering a refreshing alternative to cloud-based services. If you're looking to transition your local media collection into Immich without relying on external services like Google Photos or Amazon Photos, you've come to the right place. This guide will walk you through the various methods to import your existing pictures and videos, ensuring a smooth and efficient transition.

Understanding Immich's Core Import Mechanisms

Immich provides several pathways for importing local media, each suited to different scenarios and user preferences. The primary methods include utilizing the Immich web interface, setting up external libraries, and leveraging powerful command-line interface (CLI) tools. Understanding these methods is crucial for choosing the most effective approach for your specific needs.

The Web Interface: Ideal for Smaller Batches

For smaller sets of photos or videos, the Immich web interface offers a straightforward upload mechanism. While convenient, it might not be the most efficient for bulk imports due to browser limitations and potential timeouts for large files.

Direct Upload through the Web UI

The simplest way to add a few new photos or videos is directly through the Immich web application. This method is intuitive but generally not recommended for large-scale migrations.

Steps:

Access your Immich web interface.
Navigate to the upload section (often indicated by a cloud icon or an "Upload" button).
Select the desired photos or videos from your local machine.
Initiate the upload. Immich will process and add them to your library.

External Libraries: Maintaining Your Existing Structure

One of Immich's most powerful features for local imports is the ability to integrate external libraries. This method allows Immich to scan and index media files stored outside its primary upload directory, letting you maintain your existing folder structure on your server without duplicating files.

Configuring an External Library

External libraries are perfect if you already have an organized collection of photos and videos on your server and want Immich to manage them without moving the original files. Immich will track these assets and display them in your timeline, treating them like any other asset.

Prerequisites:

Immich instance running, preferably in Docker.
Your local media files are accessible by the Immich Docker container (via a volume mount).

Steps:

Mount Your Media Directory: Ensure your local media directory is mounted into your Immich Docker container. This is typically done by adding a volume mapping in your docker-compose.yml file. For example, if your photos are in /mnt/media/photos on your host, you might add a line like:
```
services:
  immich-server:
    volumes:
      - /mnt/media/photos:/usr/src/app/external_photos:ro # 'ro' for read-only to prevent accidental modifications
            
```
Replace /mnt/media/photos with the actual path on your host and /usr/src/app/external_photos with your desired path within the container. Make sure to use forward slashes (/).
Access Immich Administration: Log in to your Immich web UI as an administrator.
Navigate to External Libraries: Click on the "Administration" link (usually in the upper right corner), then select the "External Libraries" tab.
Create a New Library: Click the "Create Library" button.
Assign Owner: In the dialog, select the user who should own this new library.
Edit Import Paths: Click the three-dots menu next to your newly created library and select "Edit Import Paths".
Add Path: Click "Add Path" and enter the path you mounted inside the Docker container (e.g., /usr/src/app/external_photos). Click "Add" and then "Save" the new path.
Scan New Library Files: After adding the path, click the three-dots menu again and select "Scan New Library Files". Immich will begin processing the media in this directory. Depending on the size of your library, this may take some time.

Immich will load and create corresponding assets for all files in the specified path. It's important to note that Immich will not modify the original files in external libraries. All edited metadata is saved in companion .xmp sidecar files and the database.

The radar chart above visually compares the strengths of different Immich import methods. As you can see, each method excels in different areas, allowing you to choose the best fit for your specific importing needs. External libraries offer a strong balance between efficiency and maintaining your existing file organization, while CLI tools provide unparalleled control for bulk operations.

CLI Tools: The Power User's Choice for Bulk Imports

For large-scale imports, particularly when migrating an entire existing photo and video archive, the Immich Command Line Interface (CLI) and the community-maintained Immich-Go utility are the most efficient tools. These tools offer robust features for bulk uploads, deduplication, and metadata handling.

Using the Immich CLI

The Immich CLI allows you to perform various actions from the command line, including uploading assets. It's particularly useful for bulk imports where you need more control than the web UI offers.

This video demonstrates the capabilities of the Immich CLI, including instant album creation and efficient photo migration. It highlights how the CLI can streamline the process of uploading large historical image libraries to your Immich server, making it an invaluable tool for users with extensive collections.

Installation and Setup:

Before you can use the Immich CLI, you need to install it and authenticate with your Immich server.


# Install the Immich CLI (ensure you have Node.js and npm installed)
npm install -g @immich/cli

# Authenticate with your Immich server
# Replace your-immich-url and your-api-key
immich login --server http://your-immich-url --key your-api-key

Bulk Uploading Files:

Once authenticated, you can upload files from a local directory. The --recursive flag is essential for including subfolders, and the --album flag can automatically create albums based on folder names.


# Example: Upload all photos and videos from a directory and create albums
immich upload /path/to/your/photos --recursive --album

# To skip hashing files before upload (Immich still performs its own deduplication)
immich upload /path/to/your/photos --recursive --skip-hash

# Including hidden folders
immich upload /path/to/your/photos --recursive --include-hidden

Immich performs deduplication through hashing, so you don't need to worry about uploading the same file multiple times. The --skip-hash option is merely a performance consideration.

Utilizing Immich-Go for Advanced Imports

Immich-Go is a community-maintained alternative to the Immich CLI, written in Go, offering similar and extended functionalities, especially for handling Google Photos Takeout archives. While your query specifies local files, Immich-Go's from-folder subcommand is highly relevant for robust local imports.

Key Features of Immich-Go's from-folder subcommand:

Processes an entire folder tree for uploads.
Supports excluding files based on patterns.
Can use dates from filenames if metadata is missing (for common formats like JPG, MP4, HEIC, DNG, CR2, MOV).
Allows filtering imports by date range.
Manages coupled RAW and JPEG files (e.g., KeepRaw, StackCoverRaw).
Adds tags to imported assets, supporting hierarchical tags (e.g., tag1/subtag1).
Can force import of files even if JSON metadata files are missing (useful for Google Takeout, but applicable for general robust imports).

Example Usage with Immich-Go:


# Example: Upload photos from a folder, recursively, and create albums from subfolders
./immich-go from-folder --recursive --album /path/to/your/local/archive

# Example: Import files within a specific date range and add tags
./immich-go from-folder --recursive --date "2023-01-01:2023-12-31" --tag "vacation/2023" /path/to/vacation_photos

Immich-Go is particularly powerful for complex import scenarios where fine-grained control over metadata, tagging, and file handling is required.

Considerations for a Smooth Import Process

To ensure your import process is as seamless as possible, keep the following considerations in mind:

File Organization and Naming Conventions

While Immich can process files regardless of their organization, having a consistent structure can simplify management, especially if you plan to use features like automatic album creation from folder names (with the CLI). Immich also allows setting storage templates to define how uploaded files are organized on disk.

Aspect	Description	Best Practice / Immich Feature
Original File Integrity	Immich does not modify original files; metadata edits are saved in sidecar files.	Immich keeps originals untouched.
Deduplication	Immich automatically hashes files to prevent duplicates, even if uploaded multiple times.	Built-in hashing mechanism. Use `--skip-hash` for performance on CLI if sure of uniqueness.
Metadata Handling	Immich extracts metadata from files and supports XMP sidecar files.	Ensure files have correct metadata; Immich-Go can help with missing dates.
Folder Structure	Immich can import folders into albums, but its native library display is timeline-based.	Use Immich CLI/Immich-Go `--album` flag to convert folders to albums.
File Locations	Immich stores uploaded files in a managed library folder and generates transcoded versions and thumbnails. External libraries are tracked but not managed by Immich.	Configure `UPLOAD_LOCATION` in `docker-compose.yml` for managed files. Use external libraries for existing, unmanaged collections.
Large Imports	Web UI can struggle with large numbers of files; CLI/Immich-Go are more robust.	Utilize Immich CLI or Immich-Go for bulk uploads.
Error Handling	Check Immich logs and CLI output for errors during import. Ensure correct path mapping for external libraries.	Verify Docker volume mounts and container access. Run `docker exec -it immich_server bash` to check paths.

Monitoring and Troubleshooting

After initiating a large import, especially via external libraries or CLI, monitor your Immich server's logs to ensure assets are being processed correctly. Common issues include incorrect path mappings in Docker volumes or permissions problems preventing Immich from accessing the files.

Verify Paths: If using external libraries, ensure the paths in your docker-compose.yml match the paths configured in the Immich UI. You can verify Immich's access by running a shell inside the container (docker exec -it immich_server bash) and checking if you can ls the import path.
No File Modifications: Remember that Immich does not modify your original files. It saves edited metadata in companion .xmp files and its database.
Deduplication: Immich performs its own deduplication by hashing files. Even if you re-import a file, it won't be duplicated in Immich's database if it's already present.
Performance: Large imports can consume significant server resources. Ensure your server has adequate CPU, RAM, and disk I/O.

This image illustrates the Immich backup and import process, emphasizing the flow of media into the Immich system. It highlights the importance of a well-defined import strategy for managing your self-hosted photo and video collection effectively.

Post-Import Optimization and Features

Once your media is imported, Immich offers various features to help you organize and enjoy your collection:

Facial Recognition: Immich's AI-powered facial recognition automatically identifies and classifies people in your photos, making it easier to find specific individuals.
Object Detection: The system can detect objects, further enhancing search capabilities.
Timeline View: All imported assets appear in a chronological timeline, providing a familiar browsing experience akin to other photo services.
Albums: Create custom albums to organize your photos and videos, and share them with others.
Map View: If your photos contain geolocation data, you can view them on a map.

Frequently Asked Questions

What is the best method for a very large initial import?

For very large initial imports, the Immich CLI or Immich-Go are highly recommended. They provide robust bulk upload capabilities and features like recursive scanning and automatic album creation from folder structures, which are essential for migrating extensive local archives.

Does Immich modify my original photo and video files?

No, Immich does not modify your original files. It keeps them untouched. Any metadata edits or changes are saved in companion .xmp sidecar files and in the Immich database. Immich also generates transcoded versions and thumbnails for compatibility and performance.

Can Immich import existing folders and maintain their structure as albums?

Yes, when using the Immich CLI or Immich-Go, you can use the --album flag during the upload process. This feature allows Immich to automatically create albums based on the names of your local folders, effectively preserving your organizational structure within Immich.

What if I want to re-import a local library into a fresh Immich instance without duplication?

If you still have your original library folder, you can map it as a new external library in your fresh Immich instance. Alternatively, you can use the Immich CLI or Immich-Go to import the photos. Immich has a built-in deduplication mechanism based on file hashing, so even if you upload the same files, they won't be duplicated in the database.

Conclusion

Importing your local pictures and videos into Immich is a straightforward process, whether you're adding a few new files or migrating an entire historical archive. By leveraging Immich's web interface for quick uploads, external libraries for managing existing file structures, or the powerful CLI tools for bulk imports and advanced control, you can seamlessly integrate your media into your self-hosted solution. Immich's commitment to data integrity and its rich feature set make it an excellent choice for anyone looking to take control of their personal media collection.