Immich Workflows vs Scripts: What You Can Retire After v3

Immich v3 introduced native workflows, a built-in automation engine that can replace many of the custom scripts users previously relied on for tagging, file organization, and notifications. If you have scripts that handle simple metadata edits, folder moves, or webhook calls, you can likely retire them now; more complex multi-step logic with external API calls may still need a script.

Background: How Immich Automation Worked Before v3

Before v3, Immich had no built-in way to react to new uploads or metadata changes. Users who wanted automatic tagging, duplicate detection, or custom file naming had to write their own scripts and run them on a schedule or trigger them via webhooks. These scripts typically used the Immich API to query new assets, then applied their own logic with tools like jq, curl, or a Python library. This worked, but it meant maintaining a separate codebase, handling API changes, and ensuring the script ran reliably alongside the server.

What Immich v3 Workflows Can Do

Immich v3 introduces a visual workflow editor that lets you chain together triggers, conditions, and actions without writing code. The system is event-driven: it runs when a new asset is uploaded, when a face is detected, or when a metadata field changes. You can then apply actions like setting a custom tag, moving the asset to a specific album, or sending a webhook notification.

Key capabilities that cover most script use cases:

• Trigger on upload – run a workflow immediately after a new photo or video is added.
• Trigger on metadata change – react when a user edits a description, location, or date.
• Conditional logic – check if an asset has a certain tag, face, or file type before acting.
• Actions – set tags, add to albums, update metadata, or send a webhook POST.
• Reusable templates – save a workflow and apply it to multiple libraries or users.

Scripts You Can Retire After v3

If your script does any of the following, you can replace it with a native workflow:

• Auto-tagging based on filename or folder – e.g., add a “Vacation� tag when the upload path contains “2024-Italy�.
• Album organization – move assets to a specific album based on EXIF date or camera model.
• Webhook notifications – POST to a Slack or Discord webhook when a new asset is uploaded.
• Simple metadata cleanup – set a default description or location for assets missing it.
• Duplicate flagging – mark assets that share a SHA-1 hash with an existing one.

These are the most common script tasks in the Immich community, and all are now expressible as a few blocks in the workflow editor.

Scripts You Should Keep (For Now)

Not every automation belongs in a workflow. Keep your script if it involves:

• External API calls with complex response parsing – e.g., calling a machine learning service to classify images and then acting on the result.
• Batch operations on thousands of existing assets – workflows trigger on events, not on a schedule, so a one-time migration is still easier with a script.
• Custom logic not exposed in the workflow editor – e.g., reading a CSV file and updating assets based on its contents.
• Integration with other self-hosted services – if you need to query a database or interact with a service that has no webhook, a script gives you more flexibility.

How to Migrate a Script to a Workflow

Moving from a script to a workflow is straightforward if you break the script into its core steps. Here’s a typical migration path:

1. Identify the trigger – what event starts the script? Usually an upload or a metadata change.
2. List the conditions – what filters did the script apply? (e.g., “only JPEG files�, “only if no tag exists�).
3. List the actions – what did the script change? (e.g., set tag, move album, send webhook).
4. Build the workflow – in Immich v3, create a new workflow and add the trigger, then a condition block for each filter, then the action blocks.
5. Test on a small library – upload a few test files and confirm the workflow behaves like the script.
6. Disable the script – once the workflow passes testing, remove the cron job or webhook that ran the script.

Common Problems and Misconceptions

The most common mistake is assuming workflows can do everything a script can. They cannot – yet. Workflows are designed for simple, event-driven automation, not complex data manipulation. Another issue is that workflows run on the Immich server, so if your script ran on a different machine to avoid load, you may need to reconsider. Also, workflows do not have a “run now� button in the current version, so you cannot manually trigger a workflow on existing assets – that still requires a script.

A frequent misconception is that workflows replace the Immich API entirely. They don’t – the API is still there and still useful for advanced use cases. Workflows just give you a higher-level interface for common patterns.

Costs and Maintenance Considerations

Workflows have no direct monetary cost – they are part of Immich v3. The real cost is time: building and testing a workflow can take longer than writing a simple script if you are unfamiliar with the editor. However, ongoing maintenance is lower because Immich maintains the workflow engine, and you no longer need to update your script when the API changes. Scripts, on the other hand, require you to track API updates and handle errors manually.

If you have many scripts, the migration effort may not be worth it for trivial ones. But for any script that you actively maintain, the long-term savings usually justify moving to a workflow.

Alternatives to Workflows and Scripts

If neither workflows nor scripts feel right, consider these alternatives:

• Immich’s built-in duplicate detection – for deduplication, you don’t need a script at all; the server already has this feature.
• External automation tools – like n8n or Home Assistant, which can call the Immich API and give you a visual builder with more flexibility than workflows.
• Manual organization – for a small library, simple albums and tags may be enough without any automation.

Frequently Asked Questions

Can I run a workflow on existing photos?

Not directly in v3. Workflows trigger on new events (upload, metadata change). To process existing assets, you still need a script that iterates over your library and calls the API, or you can re-upload the files to trigger the workflow.

Do workflows support scheduling, like “run every night�?

No. Workflows are event-driven, not time-based. If you need a scheduled job, such as nightly cleanup, you’ll need to keep a script or use an external scheduler that calls the Immich API.

Can workflows call external APIs like Discord or Telegram?

Yes, workflows have a webhook action that can send a POST request to any URL. You can use this to notify Discord, Slack, Telegram, or any service that accepts a webhook. However, you cannot parse the response or make conditional decisions based on it – that still requires a script.

Will my existing scripts break after upgrading to v3?

No, the Immich API remains backward-compatible for the most part, so your scripts should continue to work. But you may want to migrate them to workflows over time to reduce maintenance.

Is the workflow editor available in the free version?

Yes, workflows are part of the core Immich server, which is free and open source. There is no paid tier that gates workflow features.

How do I back up my workflows?

Workflows are stored in the Immich database. You can back them up by backing up the database, or by exporting the workflow JSON from the editor if that option is available in your version. Check the Immich documentation for the exact export method.

Related

• AI Answer Replay Check Errors: Do Replies Stay in History?
• PostgreSQL Beginner’s Guide: Getting Started with Database Management
• Phone Won’t Turn On? Fixes to Try First