Best Practices for Updating Immich Server in Production Environments

Updating an Immich server in production can feel like changing the tires on a moving photo bus. It is exciting. It is useful. It can also get messy if you skip the small steps. The good news is simple. With a calm plan, good backups, and a tiny bit of testing, your update can be smooth and boring. Boring is beautiful in production.

TLDR: Never update Immich in production without a backup, a release note review, and a rollback plan. Test the update first if you can. Update during a quiet time, watch the logs, and confirm that uploads, thumbnails, search, and the mobile app still work. Treat your photo library like treasure, because it is.

Why Immich Updates Need Care

Immich is not just another app. It stores memories. Baby photos. Vacation shots. Pet chaos. Birthday cake disasters. Screenshots you forgot to delete. All of it matters.

Immich also has several moving parts. There is the server. There is PostgreSQL. There is Redis. There are machine learning services. There are background jobs. There are mobile apps. When one piece changes, another piece may need attention.

That does not mean updates are scary. It means updates deserve manners. Knock before entering. Read the room. Bring snacks. In server terms, this means backups, checks, and logs.

Start With the Release Notes

Before you pull a new image, read the Immich release notes. Yes, really. This is the seat belt step. It is not glamorous. It saves faces.

Look for words like breaking change, migration, deprecated, and required. These words are tiny alarm bells. They do not mean “panic.” They mean “pay attention.”

Check if the update requires a newer version of PostgreSQL. Check if the Docker Compose file changed. Check if environment variables changed. Check if machine learning settings changed. Also check if the mobile app needs to be updated too.

Immich moves fast. That is one reason people love it. But fast projects can change shape quickly. Do not assume your old setup is still perfect. Let the release notes be your map.

Know Your Current Setup

Before updating, write down what you have. This sounds boring. It is not. It is your “find my way home” note.

• Current Immich version
• Docker Compose file location
• Database version
• Storage paths
• Volumes and bind mounts
• Reverse proxy settings
• Environment variables
• Backup location

If you use Docker Compose, save a copy of your current docker-compose.yml and .env files. Put them somewhere safe. Label them with the date. Future you will clap.

Back Up Like You Mean It

A backup is not a vibe. It is a file you can restore. A backup is not “the data should still be there.” It is not hope wearing a hoodie. It must be real.

For Immich, you usually need two big things:

1. The PostgreSQL database, which stores metadata, users, albums, jobs, and more.
2. The upload library, which stores your actual photos and videos.

You may also want to back up profile data, configuration files, and custom storage folders. If you use external libraries, understand what is managed by Immich and what is not.

Use proper database dumps. Do not only copy the raw database folder while PostgreSQL is running. That can create a sad backup. Use tools such as pg_dump or the backup method recommended for your deployment.

After the backup finishes, test it if possible. At least confirm the files exist. Confirm the dump is not zero bytes. Confirm the photo library is present. A backup that cannot restore is just a decorative blanket.

Create a Rollback Plan

A rollback plan is a parachute. You may not need it. You will still be happy it exists.

Your rollback plan should answer simple questions:

• How do I stop the new version?
• How do I start the old version?
• Where is the old Compose file?
• Where is the database backup?
• How long would a restore take?
• Who needs to be told if the service is down?

Be careful with database migrations. Some updates change the database schema. Rolling back the container image may not be enough. You may also need to restore the old database backup. This is why the backup must happen before the update.

Use a Staging Server if You Can

A staging server is a practice stage. It lets your update trip over its shoelaces where nobody cares.

You do not need a perfect copy of production. A smaller test setup is still useful. Restore a recent database copy. Add a few sample photos. Run the update. Watch what happens.

If staging works, you gain confidence. If staging explodes, you gain information. Both are better than learning during a family photo emergency.

Image not found in postmeta

Pick a Good Maintenance Window

Do not update during peak upload time. Do not update right before a wedding. Do not update five minutes before leaving for the airport. Servers can smell fear.

Pick a quiet time. Tell users what is happening. Even if the users are just your family, tell them. “The photo server may be down for 20 minutes” is better than “Why are my vacation photos gone?”

Keep the window realistic. A small update may take minutes. A bigger update with migrations may take longer. Database restores can take much longer. Plan for the grumpy version of reality.

Pull Images Carefully

If you use Docker Compose, your update may look simple. Something like:

docker compose pull
docker compose down
docker compose up -d

Simple is nice. But do not run commands like a raccoon on a keyboard. Know which images are being pulled. Make sure your tags are correct.

Some people use latest. It is convenient. It can also surprise you. In production, many admins prefer pinning versions. A pinned version is clearer. It says, “I am updating to this exact release.” That makes rollbacks and audits easier.

If Immich documentation recommends a specific tag strategy, follow it. The goal is not to be clever. The goal is to be stable.

Stop Services Cleanly

Before applying the update, stop Immich cleanly. Let uploads finish if possible. Avoid shutting down during a big import. That is like pulling a pizza out of the oven with a leaf blower.

Use normal Docker Compose commands. Do not kill random processes unless you must. Give containers time to stop. Check that the database is not being hammered by active jobs.

If you run Immich behind a reverse proxy, you can show a temporary maintenance page. This is friendly. It also reduces strange client errors during the update.

Watch the Logs During Startup

After starting the new version, do not run away. Stay and watch. Logs are the server’s way of muttering clues.

Use something like:

docker compose logs -f

Look for migration messages. Look for errors. Look for repeated restarts. Look for database connection problems. Look for missing environment variables. A warning may be fine. A loop of doom is not fine.

Give migrations time. Some updates need to change tables or indexes. Large libraries may take longer. Be patient. Production rewards patience. It punishes button mashing.

Run a Post Update Checklist

Once the containers are up, test the application like a normal user. Not like a wizard. Like someone who just wants to see photos of a dog in sunglasses.

• Open the web interface.
• Log in.
• Upload a small photo.
• Upload a short video.
• Check thumbnails.
• Open an album.
• Search for a person, place, or object.
• Check the timeline.
• Open the mobile app.
• Confirm background backup works.

Also check admin pages. Look at job queues. Make sure background tasks are running. Confirm machine learning is healthy if you use face recognition or smart search.

Check Storage and Permissions

Many production problems are not dramatic. They are boring permission problems wearing a fake mustache.

After updating, confirm that Immich can read and write to upload folders. Check volume mounts. Check user IDs if your setup uses custom permissions. If thumbnails fail, uploads fail, or jobs complain, storage permissions may be the culprit.

Also check free disk space. Updates can create temporary files. Databases can grow during migrations. Logs can balloon if something is broken. A full disk can turn a small issue into a circus.

Keep the Mobile App in Mind

Immich has a mobile app. Production users may depend on it for automatic backup. Server updates and app versions should be compatible.

Ask users to update the mobile app when needed. If something breaks, test with the latest app version first. Also check battery settings and background activity permissions. Sometimes the server is innocent. The phone is just being dramatic.

Monitor After the Update

The update is not finished when the page loads. Keep watching for a while. Some problems appear later.

Monitor these things:

• Container restarts
• CPU usage
• Memory usage
• Database load
• Disk space
• Upload success
• Job queue health
• Error logs

If you have alerts, use them. If you do not, at least check manually. A quiet log is a lovely log.

Do Not Skip Minor Updates Forever

It is tempting to ignore updates because the server works. This is understandable. It is also risky.

Small updates often include bug fixes, security fixes, and migration steps. If you wait too long, one future update may become a giant leap. Giant leaps are where ankles get twisted.

A good rhythm is better. Review releases often. Update when stable. Avoid day one updates for critical production unless the fix is urgent. Give the community a little time to find sharp edges.

Document What Happened

After the update, write down what you did. Include the old version, new version, date, backup name, and any problems. This takes five minutes. It can save an entire afternoon later.

Your notes do not need to be fancy. A simple update log is fine.

Date: 2026-02-10
Old version: x.y.z
New version: x.y.z
Backup: immich backup before update
Result: success
Notes: migrations took 8 minutes

This is how you become the calm admin in the movie. Not the one yelling at a blinking cursor.

Final Thoughts

Updating Immich in production is not about being fearless. It is about being prepared. Read the release notes. Back up the database and library. Test when possible. Update during a quiet window. Watch the logs. Check the app. Keep notes.

Most updates will be simple when you build a good routine. The routine is your safety net. It turns “Oh no” into “All good.” And that is exactly what you want when the server holds years of memories, memes, and magnificent blurry cat photos.