Have you ever felt that slight frustration when you have a folder full of precious photos and videos on your computer, and you need to get them into your Immich self-hosted library? You open the web browser, drag and drop, maybe wait for a progress bar, and hope nothing interrupts the connection. For a few photos, it’s fine. But for thousands? For regular backups? It feels a bit… clunky. I’ve been there too.
That’s where immich-go comes in, and it completely changed how I interact with my personal photo server. If you’re running Immich, this little command-line tool might be the most powerful upgrade you’re not using. It turns the chore of uploading into a fast, reliable, and even automated process. Let’s walk through what it is, why it’s fantastic, and exactly how you can use it, even if you’ve never touched a command line before.
What Exactly is Immich-Go?
In simple terms, immich-go is a command-line interface (CLI) tool for the Immich self-hosted photo service. Think of it like this: the Immich web app is your beautiful, user-friendly living room where you view and organize your photos. Immich-go is the efficient, powerful workshop in the garage where the heavy lifting gets done.
It’s a single program you run from your computer’s terminal or command prompt. Instead of clicking buttons, you type text commands like immich-go upload --album="Vacation 2024" ./photos/. This tells the tool to send all photos from a folder named “photos” to your Immich server, neatly placed into an album called “Vacation 2024.” It’s built for speed, for automation, and for handling massive libraries without breaking a sweat. It’s the tool for photographers, tech enthusiasts, or anyone who wants more control.
Getting Started: Installation Made Simple
Don’t let “command line” scare you. Installing immich-go is straightforward. The tool is a single, standalone file. You can find the latest release on its official GitHub page (just search for “immich-go releases”). You’ll see downloads for Windows (a .exe file), macOS, and Linux. Choose the one that matches your system.
For most users, the easiest way is to download the file, place it in a convenient folder (maybe C:\immich on Windows or ~/immich on Mac/Linux), and then add that folder to your system’s “PATH.” Adding to PATH sounds technical, but it just means telling your computer where to find this program so you can run it from anywhere. There are plenty of simple tutorials online for “how to add folder to PATH on [your OS]” if you get stuck. The immich-go GitHub page also has clear instructions.
Once it’s installed, open your terminal (Command Prompt or PowerShell on Windows, Terminal on Mac/Linux). Type immich-go version and hit enter. If you see a version number pop up, congratulations! You’re ready for the next step.
The Essential First-Time Setup
Before immich-go can talk to your Immich server, you need to introduce them. This requires two pieces of information: your server’s address and a special key.
-
Your Immich Server URL: This is the web address you use to access Immich, like
https://photos.yourdomain.comorhttp://your-local-ip:2283. -
An API Key: This is a secure password for programs, not people. To get it, log into your Immich web interface. Go to Settings > Users > API Keys. Click “Generate New Key,” give it a descriptive name like “Immich-Go Laptop,” and copy the long string of characters it gives you. Store this safely!
Now, back in your terminal, you’ll run the configure command:
immich-go configure --server https://photos.yourdomain.com --key YOUR_API_KEY_HERE
Replace the URL and key with your own. The tool will save this information, so you only have to do it once per computer. It’s like logging in permanently for this tool, which is perfect for automation.
Mastering the Core Commands: Upload, Sync, and Explore
With setup done, the real fun begins. Here are the commands you’ll use most.
The Workhorse: upload
This is the main command. Its basic form is:
immich-go upload /path/to/your/photos
It will recursively scan that folder and all subfolders, uploading every photo and video it finds. But its true power is in the options:
-
--album: Creates an album from the uploaded items. You can use--album="%Y/%m"to auto-create albums by year and month based on the photo’s date! -
--album="%pathname": Creates albums that mirror your folder structure on disk. -
--skip-duplicates: A lifesaver. It checks if a file (based on its unique hash) is already on the server and skips it. This makes re-running the command safe and fast. -
--include/--exclude: Filter by file extension, like--include="*.jpg,*.cr2,*.mp4".
A typical command I use after a photoshoot looks like:
immich-go upload --album="2024-05-15 Garden Project" --skip-duplicates ./DCIM/
It’s fast, organized, and I know duplicates won’t clutter my library.
The Organizer: album
Want to manage albums from the CLI? You can. immich-go album list will show all your albums. You can also create albums or add assets to them directly, though I find the upload command’s --album flag covers 99% of my needs.
The Explorer: stat and info
Curious what immich-go would do? Run immich-go stat /path/to/photos. It gives you a dry run, showing how many files it found, how many are new, etc., without uploading anything. The info command shows your server and user details.
Why Bother? The Compelling Advantages Over the Web UI
You might be thinking, “The web uploader works fine for me.” And it does, for small tasks. But here’s where immich-go shines:
-
Unmatched Speed and Reliability: The CLI uses a more efficient transfer method. It handles network interruptions better. For bulk transfers of tens of thousands of files, it’s not just faster; it’s dramatically more stable. I’ve had browser uploads time out or crash. Immich-go just powers through.
-
True “Set and Forget” Automation: This is the killer feature. On a Linux server or NAS, you can set up a cron job. On a Mac, you can use launchd. On Windows, a scheduled task. You can point immich-go at a folder (like your phone’s backup folder or your camera’s SD card dump location) and have it run every night. Your photos auto-sync to Immich while you sleep. Once configured, you never have to think about uploading again.
-
Perfect for Servers and Headless Systems: If your Immich instance runs on a server in a closet (or in the cloud), immich-go is the natural way to feed it photos from other machines or automated processes. No graphical interface needed.
-
Superior Metadata Handling: In my experience, immich-go is exceptionally consistent at reading and preserving file creation dates (the “original date” of the photo). When you upload via the web, sometimes the “upload date” can get mixed up, messing up your timeline. Immich-go prioritizes the embedded EXIF date, keeping your chronology perfect.
-
Power User Control: The fine-grained control over includes, excludes, and album creation logic is something the web UI simply doesn’t offer. It turns uploading from a manual task into a precise, repeatable operation.
Pro Tips and Personal Workflow
Let me share how I use it. My photos live on a central NAS. My Immich server runs in a Docker container on a different machine. On the NAS, I have a simple script that runs via cron every Sunday at 3 AM. The script is just:
/usr/local/bin/immich-go upload --skip-duplicates --album="%pathname" /shared/Photos/
The %pathname flag means my folder structure (e.g., /shared/Photos/2024/05/) becomes an Immich album named “2024/05”. My entire library, organized by folder, is continuously and incrementally synced to my personal cloud. I haven’t manually uploaded a photo in over a year.
Another great use is migration. When I left Google Photos, I used Google Takeout, which gave me a nightmare folder of JSON files and images. I used a script to organize it, and then used immich-go to upload the entire 80GB mess. It ran for two days straight, without a single hiccup. Trying that in a browser would have been impossible.
Conclusion
Immich-go transforms Immich from a great photo viewer into a robust photo management ecosystem. It addresses the most significant pain point of self-hosting—getting large volumes of media into the system—with elegance and power.
If you’re an Immich user with more than a casual interest, investing an hour to learn immich-go will pay dividends forever. It reduces friction, ensures consistency, and gives you back the ultimate luxury: time. You stop being the upload mechanic and start being the curator of your memories. Give it a try, start with a small folder, and feel the difference. You might just find, as I did, that it becomes the only way you interact with your Immich server’s backend.
Frequently Asked Questions (FAQ)
Q: Do I need to be a programmer to use immich-go?
A: Not at all! You need to be comfortable following step-by-step instructions for your operating system, mainly for installation. The commands themselves are simple text. Think of it like learning a few special phrases rather than a whole language.
Q: Is it safe? Will it delete files from my computer?
A: Absolutely safe for your originals. Immich-go only reads files from your computer to upload them. It never modifies, moves, or deletes the source files. The --skip-duplicates option only checks the server, not your local files.
Q: Can I use it to download photos from Immich back to my computer?
A: No, immich-go is currently designed as an upload and management tool. For downloading, you should use the Immich web interface’s download function or the official mobile app’s backup feature.
Q: How does it compare to the official Immich CLI?
A: The official Immich project is developing its own CLI tool. As of now, immich-go is a mature, third-party tool that is incredibly feature-complete for uploads. The official CLI may eventually become the standard, but for robust, automated uploading today, immich-go is a proven and excellent choice.
Q: What if I get an authentication error?
A: Double-check your server URL and API key. Ensure your Immich server is accessible from the computer where you’re running immich-go (try pinging the URL). Also, verify that your API key hasn’t been revoked in the Immich settings.
Q: Can I run multiple upload jobs at once?
A: It’s technically possible, but it’s generally not recommended as it can put unnecessary load on your server and cause conflicts. It’s better to queue your uploads or point a single job at a parent folder.
Read Also: FirmAE Explained: A Beginner’s Guide to IoT Firmware Emulation
