Immich Power Tools: Bulk Organizing for Your Immich Library
Power tools for organizing your immich library. Immich Power Tools A unofficial immich client to provide better tools to organize and manage your immich account.
At a glance
- What is it?
- Immich Power Tools is an unofficial client that adds bulk editing, smart search, and analytics to Immich. It works alongside your existing Immich server, but it requires direct database access and an API key with full permissions.
- Who is it for?
- Adopt Immich Power Tools if you manage a large Immich library and spend too much time editing people, albums, or dates one asset at a time. It fits self-hosters who already run Docker Compose and can give the tool direct access to the Immich Postgres database.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: Immich's Built-In Organizing Is Too Manual
Immich is a solid photo server, but its organizing features are per-asset. The author of Immich Power Tools says they migrated a Google Photos library to Immich and found that matching people and managing albums required opening each asset individually. This tool is for people who have thousands of photos and want to fix dates, merge duplicate people, or fill missing locations in bulk. It is not a replacement for Immich. It is a companion that talks to the same server and database. The target user is someone who already runs Immich and is comfortable with Docker and environment variables.
How It Works: API Key Plus Direct Database Access
Immich Power Tools is a Next.js web app that acts as a client to your Immich server. It uses the Immich API for most operations, which is why you must provide an API key. The README explicitly says to select all permissions for that key. That is a serious security consideration. The tool also reads from the Immich Postgres database directly. You must set DB_HOST to the name of the Immich database container, which by default is immich_postgres, and DB_PORT to 5432. This direct access is what enables features like potential albums and people merge suggestions, because those require queries that the public API may not support. The tradeoff is that you are giving an unofficial tool credentials to your database, so you should run it on an isolated network and restrict access to the Power Tools UI.
Getting It Running: Docker Compose and Environment Variables
The recommended install is via Docker Compose. You add a service to your existing docker-compose.yml, using the image ghcr.io/immich-power-tools/immich-power-tools:latest. You mount a volume for /app/data, expose port 8001:3000, and set an env_file. The required variables are IMMICH_API_KEY, IMMICH_URL, EXTERNAL_IMMICH_URL, DB_PORT, and DB_HOST. The README shows a sample where IMMICH_URL is set to the local IP of your Immich instance and EXTERNAL_IMMICH_URL is the external address. The DB_HOST must match the name of your Immich Postgres container. For local development, you clone the repo, copy .env.example to .env, fill in IMMICH_URL, IMMICH_API_KEY, DB_USERNAME, DB_PASSWORD, DB_HOST, DB_PORT, and DB_DATABASE_NAME, then run bun run dev. The project uses bun, not npm or yarn, so you need bun installed.
The Features That Justify the Setup
The feature list is concrete. Bulk people management lets you update person data with advanced filters, and the merge suggestion feature groups similar faces so you can merge them in bulk. Missing location finds assets without GPS data and updates them using the location of the asset, which presumably means the location of a nearby asset or the album. Potential albums suggests albums that could be created based on assets and people. Analytics shows assets over time and EXIF data. Smart Search, called Find, accepts natural language queries like "show me all my photos from 2024 of <person name>". Bulk Date Offset shifts the date of selected assets by a fixed amount, which is useful for fixing timezone errors. These are all operations that would take hours if done manually in the Immich UI.
Smart Search and the AI Dependency
The Find feature is not a local search index. It sends your search text to an OpenAI-compatible API for parsing. The README says you can use OpenAI, Groq, Ollama, or LM Studio. It also states that no personal library data is sent, only the search text. That is a meaningful privacy boundary, but it still means the feature is useless without an external AI endpoint. If you do not configure AI_API_KEY, AI_BASE_URL, and AI_MODEL, the Find page will not work. The default model is gpt-4o-mini, but you can point it at a local Ollama instance by setting AI_BASE_URL to http://host.docker.internal:11434/v1. This is a flexible design, but it adds a moving part. If you self-host everything, you need to run an Ollama container and keep it healthy, or the search feature degrades.
A Real Limitation: Version Locked to Immich 3.0
The README carries an important warning: v0.22.0 and above require Immich 3.0 or newer. That means if you are on an older Immich release, you cannot use the latest Power Tools. The project releases frequently, with v0.22.0 pushed on 2026-07-02, so the maintainer is actively iterating. But this also means the tool is tied to Immich's API and database schema. When Immich updates, Power Tools may break until a new release comes out. The README does not mention any rollback or compatibility mode. If you value stability over new features, you might want to pin the Power Tools image version to one that matches your Immich version, and test after any Immich upgrade.
Alternatives: The Immich CLI and Manual Bulk Tools
The obvious alternative is the Immich CLI, which Immich itself provides. The CLI can perform certain bulk operations, like uploading and asset management, but it does not offer people merge suggestions or potential albums. The Power Tools README links to the Immich CLI documentation for obtaining an API key, which shows the two are complementary. Another alternative is writing custom scripts against the Immich API. That gives you full control but requires programming effort. Power Tools is a ready-made UI that wraps those API calls, so it is faster to adopt if you do not want to build your own tooling. The difference is that the CLI is official and stateless, while Power Tools is unofficial, stateful (it stores data in its own /app/data volume), and requires database access.
Maintenance and License Considerations
The project is licensed AGPL-3.0. That means if you modify and distribute it, you must share your source code. For personal self-hosting, that is rarely a concern, but it matters if you plan to offer it as a service. The repository is active, with recent releases and a default branch that is not archived. The README does not describe an upgrade path, but the Docker image uses the latest tag, which will pull new versions. You should back up /app/data before upgrading, because there is no mention of migrations. The tool also depends on external services: Google Maps for the heatmap, and an AI provider for Find. Both are optional, but they are external calls that you should be aware of. The README explicitly says no personal data is sent to Google Maps beyond location data for the heatmap, and no library data to the AI provider, only search text.
Editorial conclusion
Adopt Immich Power Tools if you manage a large Immich library and spend too much time editing people, albums, or dates one asset at a time. It fits self-hosters who already run Docker Compose and can give the tool direct access to the Immich Postgres database. Do not adopt it if you are on Immich 2.x, since v0.22.0 and above require Immich 3.0. Also avoid it if you are uncomfortable granting an unofficial tool an API key with all permissions and direct database credentials. Before deploying, verify that your Immich version is 3.0 or newer, that your Postgres port is reachable from the Power Tools container, and that you have an OpenAI-compatible endpoint ready if you want the Find feature. Check the release notes for v0.22.0 to confirm the exact database schema changes, because any future Immich update could break compatibility.
Community notes