Immich Power Tools: bulk people, album and location management for Immich libraries

The gap Immich Power Tools fills in a self-hosted photo library

Immich's own UI is built around looking at one asset, one person or one album at a time. The project's back story in the README is explicit about where that hurts: the author migrated an entire Google Photos library into Immich with albums intact, then found people matching and bulk organization lacking, and describes the Immich UI as "quite restricted" for organizing content. Immich Power Tools exists to close that specific gap. It is an unofficial client, not a fork and not a plugin, and it is aimed at people who have already finished the hard part of a migration and are now staring at thousands of assets that need the same correction applied.

The feature list maps directly onto that audience. Manage people data in bulk with filters. Merge people based on suggested face similarity. Find assets with no location and fill them in. Surface albums that could exist given the people and assets already in the library. Offset dates in bulk for assets whose timestamps are out of sync. If your library is small enough that you can fix things by hand, none of this is worth a second container. If it is not, the bulk operations are the whole point.

How Power Tools reaches your library: API calls plus a direct Postgres connection

The architecture is a Next.js application (the tech stack lists Next.js, Tailwind CSS, Shadcn and Axios) that runs as its own service next to Immich. It talks to Immich two ways. The first is the Immich API, authenticated with IMMICH_API_KEY. The second is a direct connection to the Immich Postgres database, configured through DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD and DB_DATABASE_NAME. That second path is why the README insists the power-tools container sit on the same Docker network as Immich, and why DB_HOST defaults to the name of the Immich database container, immich_postgres.

The project keeps its own state separately. The .env.sample shows APP_DB_PATH for a SQLite application database, defaulting to ./data/app.db, and the Docker Compose and Dockerfile both mount a named volume at /app/data. The Dockerfile also copies the Drizzle migrations directory into the runtime image, so schema changes are applied at startup rather than by a manual step. Two databases, two failure modes: if the Immich Postgres connection is wrong you get the database connection failure people search for, and if the /app/data volume is not persisted you lose Power Tools' own state across container replacement.

Immich Power Tools install with Docker Compose

The recommended path in the README is Docker Compose, adding Power Tools as a service beside your existing Immich services. The compose file below is the service block from the README, which maps host port 8001 to the container's 3000 and persists /app/data in a named volume.

services:
  power-tools:
    container_name: immich_power_tools
    image: ghcr.io/immich-power-tools/immich-power-tools:latest
    volumes:
      - immich-power-tools-data:/app/data
    ports:
      - "8001:3000"
    env_file:
      - .env

volumes:
  immich-power-tools-data:

With that service up, the container listens on 3000 internally and 8001 on the host. Note that the repository's own docker-compose.yml uses a 3000:3000 mapping instead, so if you copy that file rather than the README block you will expose a different port. Pick one and stay consistent.

The environment file is where most installs go wrong. Beyond the Immich URL and API key you already have, Power Tools needs the database coordinates, and DB_HOST must be the name of the Immich database container, not localhost.

IMMICH_API_KEY= # your_immich_api_key
IMMICH_URL = "http://local-ip-of-immich:port" # Your immich instace ip address and port
EXTERNAL_IMMICH_URL = "https://external-address" # External address of immich

DB_PORT = "5432"
DB_HOST = "immich_postgres"

The README states that when you create the API key you should select all permissions. That is a broad grant, and it is worth understanding before you paste the key in. For a Portainer-based install the README gives a docker run form plus a network attach:

docker run -d --name immich_power_tools -p 8001:3000 -v immich-power-tools-data:/app/data --env-file .env ghcr.io/immich-power-tools/immich-power-tools:latest
docker network connect immich_default immich_power_tools

For local development the project asks for bun, with .env copied from .env.example, and the dev server started with bun run dev. The .env.sample also lists SECURE_COOKIE, JWT_SECRET, POWER_TOOLS_ENDPOINT_URL and APP_DB_PATH, none of which the README explains in prose.

The Immich 3.0 requirement and other hard limits

The most consequential constraint is stated at the top of the README: Power Tools v0.22.0 and above require Immich 3.0 or newer. If you are pinned to an older Immich release, you cannot simply take the latest image. The release history shows v0.21.4 and v0.21.3 predating that line, so an older Immich install implies an older Power Tools tag, and the README does not document a support matrix for those combinations.

The database dependency is the second limit, and it is structural rather than a bug. Because Power Tools reads the Immich Postgres database directly, your database port has to be reachable from the Power Tools container, and the README's local development note says to make sure the Postgres port is exposed on your machine. On a hardened deployment where the database is only reachable from the Immich server container, this tool does not fit without loosening that boundary. The README does not document rollback for a bulk operation, and it does not describe an undo path. Bulk date offset and bulk people merge are the kind of operations where an undo would matter, so treat the absence of documented rollback as a real risk rather than an oversight.

Optional integrations add their own caveats. The heatmap uses a Google Maps JavaScript API key, and the README says only location data is sent to Google Maps, pointing at src/pages/assets/geo-heatmap.tsx. Smart Search in the Find page uses any OpenAI-compatible provider, including Groq, Ollama or LM Studio, and the README states that only your search text is sent, not library data. Both statements are the project's own claims about data flow, and both are worth reading in the source before you enable them.

How Power Tools compares with Immich Kiosk and Immich Optimizer

The related searches around this project frequently pair it with Immich Kiosk and Immich Optimizer, and the three do different jobs. Immich Kiosk is a display client: it puts your library on a screen, which is a presentation problem. Immich Optimizer is about the media files themselves, reducing or re-encoding them, which is a storage problem. Power Tools is neither. It is an editing client for metadata and structure: which person is on which face, which album should exist, which asset is missing a location, which timestamp is wrong by a fixed offset.

The practical difference is what you point each one at. Kiosk wants a browser and a screen. Optimizer wants your asset files. Power Tools wants the Immich API and the Immich Postgres database, and it needs write-level access to both. That makes it the most invasive of the three to install and also the only one that changes your library rather than reading it or re-encoding it. If your complaint is that your library looks wrong on a wall display, Power Tools is the wrong tool. If your complaint is that six hundred faces are attached to the wrong person, it is the right one.

Maintenance status, licence and what upgrading costs you

The repository is not archived. The last push was on 2026-07-02, which is the same date as the v0.22.0 release, and v0.21.4 and v0.21.3 landed on 2026-05-21 and 2026-05-01. The gap between the last push and today is under six months, so the project is being worked on, but the cadence is worth noting: roughly a release every six to eight weeks through that window, not continuous churn.

Upgrades are the cost centre. Because Power Tools pins compatibility to Immich versions, an Immich upgrade can force a Power Tools upgrade in lockstep, and the reverse is also true. The Dockerfile copies Drizzle migrations into the image and the package scripts expose db:generate, db:migrate and db:studio against drizzle.app.config.ts, so the application database has its own schema lifecycle. The image runs as a non-root nextjs user with /app/data owned by that user, which means a volume created by a different UID can fail to be written. The Dockerfile also carries a comment about copying @libsql and libsql native binaries because Next.js standalone tracing misses dynamically required native modules, which is a build detail that can bite anyone rebuilding the image themselves rather than pulling the published tag.

The licence is AGPL-3.0, per the repository. That is a copyleft licence with a network-use clause. Running it as a service for yourself is one thing; the obligations become more interesting if you modify it and expose it to other users. This is not legal advice, and the LICENSE file is the authority, not this paragraph.

Editorial conclusion

Adopt Immich Power Tools if you have already migrated a large library into Immich and the per-asset editing in the Immich UI is the bottleneck, and if you can give it direct Postgres access and an API key with all permissions. Do not adopt it if you run Immich without an exposed database port, if you are on Immich older than 3.0 and need v0.22.0 or above, or if you are unwilling to grant a third-party container full API permissions. Before you commit, verify three things: that DB_HOST resolves to your Immich Postgres container on the shared network, that the Postgres port is reachable from the Power Tools container, and that your Immich version matches the compatibility line in the README.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes