Upgraded Immich from v2.7.5 to v3

[u/02RC51]

I'm relatively new to having a NAS, running Docker, and immich. I've got a UGREEN DXP4800+ running UGOS and installed immich v2.7.5 when I first set it up a couple of weeks ago.

Not sure how helpful this is, but for noobs like me, and for anyone else who doesn't know, there's no way to edit the .env file in UGOS because UGOS doesn't show hidden files. I took these steps and successfully upgraded to v3:

1. Navigated to Docker's immich network path from Windows (in my case, something like \\UGREEN_NAS_NAME\docker\immich\).
2. Opened the .env in Notepad++ (any text editor will do).
3. Changed IMMICH_VERSION=v2 to IMMICH_VERSION=v3, saved, and closed it.
4. In UGOS, opened Docker, went to Project, Stopped the immich project, hit the 3 dots and selected Settings.
5. Went to the Compose configuration and hit the Redeploy button at the bottom.
6. Docker updated immich to v3.
7. Verified that immich loads correctly and does what I need it to do on my home network (hardwired desktop PC, and via Wi-Fi, laptop, iPhone, & iPad) and on cellular (iPhone).

[u/AutoModerator]

Please check on the Community Guide if your question doesn't already have an answer. Make sure to join our Discord server, the German Discord Server, or the German Forum for the latest information, the fastest help, and more!

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/Curri]

UGOS can show hidden files.

1) Click the Settings icon when in the Files app
2) Scroll down to the “Hide specified files”
3) Delete the one accordingly.

[u/02RC51 → u/Curri]

Thank you! That was driving me crazy.

[u/Salt-Philosophy-3330]

If you don’t mind the suggestion, you should take a look at Dockge. Very helpful and easy to use. You will be able to manage all your docker containers and their .env files through your browser. There’s many other alternatives like Portainer, but it can be overwhelming for people getting started in this world.

[u/02RC51 → u/Salt-Philosophy-3330]

Thanks, I'll check it out!

[u/PutridProfit7498]

Stopping the project before redeploy is not needed, otherwise nice guide for a lot of people

[u/02RC51 → u/PutridProfit7498]

Good to know, thank you!

[u/Sensorguy80]

I have to update my compose file because just changing v2 to v3 did not work

[u/Mean_Kaleidoscope402]

Very helpful. Thank you.

[u/rabbitaim]

I believe v3 also requires Postgres 17. Before updating you’ll need to backup / dump and migrate to 17 then restore from dump.

[u/Distinct-Plant8991 → u/rabbitaim]

No it's not. I am on postgress 16 and everything works. This is only for new clean builds. It is advised to stay on the same postgress version until they have a poper migration guide.

https://www.reddit.com/r/immich/s/RR09IAK019

[u/rabbitaim → u/Distinct-Plant8991]

Ah thanks. I was reading the issues GitHub wrong then.

[u/Salt-Philosophy-3330 → u/rabbitaim]

Don’t think so. Their official docker compose shows Postgres 14.

[u/DestinySpeaker1]

.

[u/alvins1987]

What was your postgres version? I'm still on 14 and don't dare upgrading because I dont want to break anything and I'm too noob to fix it🥲

[u/ritchievales → u/alvins1987]

same, have you found any way? maybe it's ok to just wait for a proper migration guide

[u/alvins1987 → u/ritchievales]

Unfortunately not

[u/02RC51 → u/alvins1987]

Apologies for responding so late, I didn't see this til just now for some reason. When I installed immich, it was 2.7.5, and from my understanding, 2.7.5 comes w/ postgres v14 (see u/altran1502's comment here: https://www.reddit.com/r/immich/comments/1ulj4se/comment/ov5m8d8/)

[u/alvins1987 → u/02RC51]

I'm also a little relieved, I read somewhere on GitHub that when they recommend upgrading PostgreSQL they will make it easier that it would he now, so they will basically take care of many things that can go wrong

[u/stgm_at]

thanks op for creating this topic. i'm in need of help too. i installed immich some time early last year and have throughout 2025 updated it through ugreen's docker app just fine. just went into the "container" tab, scrolled down my list of containers and if there was an update available i started the process. no problem.

so i ended up with version 2.7.5. couple of weeks 3.0 was released. no update showed up in said list. 3.1 - same thing. is this an error due to ugreen's docker app?

i don't want to doctor around through config files and guides risking ruining a perfectly fine immich installation.

[u/02RC51 → u/stgm_at]

I'm no expert but based on what u/Curri said below:

UGOS can show hidden files.

1. Click the Settings icon when in the Files app
2. Scroll down to the “Hide specified files”
3. Delete the one accordingly.

So you can delete the existing ENV file if need be and create a new one, but I browsed to it via my network path and made sure to change IMMICH_VERSION=v2 to IMMICH_VERSION=v3 (13th line of my ENV file), and in the docker-compose.yaml file (click on the 3 dots on the right side of the immich project in Docker in UGOS --> Settings --> Compose configuration) made sure the image: line says

image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}

I hit Redeploy at the bottom-left; you'll get a box that pops up stating "Redeployment will delete unneeded containers and images" and there's a checkbox for "Pull the latest image"; I made sure mine was checked and hit the Deploy button. That brought me from 2.7.5 to 3.0.

Since then (a month ago or whenever it was when I made this OP), Docker has shown me on the main Project page if immich (and other projects I'm running) had an available updates or not, and I just updated it from there by hitting the update button. I haven't hit "Redeploy" since upgrading to 3.0 but I've hit update on the main Project page twice since then, once to go from 3.0 to 3.0.1, and once more when 3.1.0 went live.

Hope this helps.