1. Developer Guide: Immich Autotag

July 22, 2026 ยท View on GitHub

This document is intended for contributors and developers. Here you'll find information about project structure, development workflow, architecture, and technical details relevant for contribution and maintenance.

For user documentation, onboarding, and execution options, see the README.md , which now includes both quick start and useful links for review and daily use.

1.1. Installation and Environment Setup

  1. Clone the repository.
  2. Run the script to create and activate the virtual environment, install dependencies, and generate the client:
source setup_venv.sh

This script:

  • Creates and activates the .venv virtual environment.
  • Installs external dependencies from requirements.txt.
  • Installs openapi-python-client if not present.
  • Automatically generates the immich-client/ folder (with hyphen) from the official OpenAPI spec if it does not exist.
  • Installs the local client in editable mode.
  • Prepares the environment for development and testing.
  1. If you need to regenerate the client, delete the immich-client/ folder and rerun the script.

1.2. Execution

Run the main application:

./run_app.sh

You can also check the README.md for other execution options, such as pipx or Docker (in progress).

1.3. Structure

  • immich_api_examples/: Example scripts showing how to use the Immich API and test integration:
    • immich_api_example_read_asset_tags_albums.py: Example for reading asset tags and albums.
    • run_test_asset_albums_tags.sh: Script to run the above example in the correct environment.
  • main.py: Main entry point for Immich AutoTag.
  • run_app.sh: Script to launch the application.
  • setup_venv.sh: Script to create the environment, install dependencies, and generate the client.
  • requirements.txt: External project dependencies.
  • immich-client/: Autogenerated client from OpenAPI (with hyphen).
  • immich_autotag/: Main package with all core logic, helpers, and configuration:
    • core/: Wrappers, analyzers, and context classes.
    • utils/: Helper functions and utilities.
    • config/: Configuration modules:
      • user_config.py: User-editable configuration (host, API key, tags, etc.)
      • user_config_template.py: Template for user config (no private data)
      • internal_config.py: Internal, non-user config (derived variables, internal flags)
  • scripts/: Utility scripts for project hygiene and automation:
    • clean_pycache.sh: Cleans all .pyc files and __pycache__ folders in the project.
  • LICENSE: GPL v3 license (local link).
  • README.md : Main documentation and user guide.

1.4. Custom Developer Configuration

For security reasons, do not upload your immich_autotag/config/user_config.py file with private data to the public repository.

Instead, use the template immich_autotag/config/user_config_template.py:

  1. Copy the file immich_autotag/config/user_config_template.py as immich_autotag/config/user_config.py.
  2. Edit the host, port, and API_KEY values to match your Immich instance.
  3. Modify the tags and patterns as needed for your use case.

The template file does not contain sensitive information and can be uploaded to the repository as a reference for other users.

Upcoming sections:

  • Testing and test automation
  • Contribution and style guide
  • Continuous integration and deployment
  • Docker execution
  • More advanced examples