Object storage #23745
Replies: 49 comments 27 replies
-
|
The advantages aren't clear to me after reading- can you elaborate? Seems like the pitch is that it fixes orphaned assets and availability during storage migrations, but I'm failing to see how object storage fixes this as opposed to anything else (storing photos in the DB, flat filesystem indexed by DB, etc.) |
Beta Was this translation helpful? Give feedback.
-
|
@tonya11en This is possible with a regular file system, but there has been a lot of push back for implementing the proposal for it. The current model is fundamentally incompatible with object storage, and so the proposed safe and efficient structure is required. It may be possible to introduce some configuration option to completely disable storage migration and use this proposal for block storage too, but I am not sure if it's worth the confusion at current. I'd much rather implement object storage and gather feedback. I have started work on this, so hopefully I can show it soon. |
Beta Was this translation helpful? Give feedback.
-
|
I think the tldr is that if you don't ever move the file after it is uploaded you get a simpler system. It has been discussed several times before and we have no immediate plans to drop support the storage template feature. |
Beta Was this translation helpful? Give feedback.
-
|
Apart from the technical benefits, object storage can be rented way cheaper on providers like backblaze, scales without re-partitioning drives and has become pretty standard for theses applications as it makes deployment in clouds a lot easier and cleaner. I'm eagerly awaiting the S3 support of immich to be able to migrate all my photos. Currently running a self hosted Nextcloud instance on a small VPS with external S3 storage via backblaze. So, TL;DR: please strongly consider adding native support 🙂 |
Beta Was this translation helpful? Give feedback.
-
|
#5917 will help - as it allows storage migration to be disabled. |
Beta Was this translation helpful? Give feedback.
-
|
To sum up discussion from Discord:
It is evident that there is pushback from the team against radical changes to the directory layout that may hinder performance. What would an MVP for cloud storage support look like? |
Beta Was this translation helpful? Give feedback.
-
I would argue this is not the case at all and listing files is not a normal part of operation for Immich at all. It is only used for the repair page, and should run infrequently (if ever). There was also discussion of backups and how that may take a while, but I would also argue it should be an infrequent operation. Regardless, it seems important to some users, so we should try to optimise for this case. @bo0tzz proposed we move forward with an object storage implementation and answer some of these questions later, as to make progress, which I agree with.
I don't think this would be sensible. The whole point of object storage support is to be fast and reliable. We should try to understand how to read directly from object storage rather than add additional complexity (i.e persisting things in multiple places). |
Beta Was this translation helpful? Give feedback.
-
I can't be the judge of that, but it looks like that there is no consensus about that amongst the developers, so a conservative approach to this seems correct.
I believe that this complexity is inherent to the problem though. Object storage can be the long-term destination for the assets, and assets can be delivered directly from there. However, operations such as metadata extraction and thumbnail generation work with the local filesystem and it would be difficult to change that. |
Beta Was this translation helpful? Give feedback.
-
This is true, but I think the best approach there would be for the microservices instances to keep a cache folder that they download files into, rather than having files go to local storage -first- before being uploaded to S3. |
Beta Was this translation helpful? Give feedback.
-
If I understand correctly, the two proposed ways of operation for the microservices are very similar - check if the target asset is present in the local filesystem (it doesn't matter if we call it a cache), if not, fetch it from the object storage. Then proceed with whatever the microservice does. If the uploads folder is on the local filesystem, we 1) save ourselves one roundtrip to the object storage and 2) won't need to rename the uploaded file after we extract the metadata. What are the advantages of the object-storage-first approach? |
Beta Was this translation helpful? Give feedback.
-
|
The advantage is consistency, knowing for a fact that if an asset is in Immich, it is absolutely also in the object storage. It also means that the server and microservices instances can be decoupled further, no longer requiring a shared filesystem. |
Beta Was this translation helpful? Give feedback.
-
Fair enough. What would be the way forward with object storage support though?
|
Beta Was this translation helpful? Give feedback.
-
|
The past few days have seen significant discussion of the object storage topic amongst the maintainer team. There's no full consensus yet, but one thing that seems clear is that there will be a need for significant refactoring around how we store and handle files before object storage can be approached directly. That means cases such as abstracting away the current (filesystem) storage backend behind a common interface and using file streams throughout the code base rather than directly accessing paths. (I'll let @jrasm91 chime in on what other refactors might be needed). |
Beta Was this translation helpful? Give feedback.
-
|
As a workaround, maybe https://github.com/efrecon/docker-s3fs-client could help? Has anyone tried using mounting S3 with FUSE? |
Beta Was this translation helpful? Give feedback.
-
I currently run immich with the rclone docker volume driver and it is perfectly usable. |
Beta Was this translation helpful? Give feedback.
-
I finally had some time to reconcile my branch to Images are also available here: https://hub.docker.com/r/enarciso/immich-server & https://hub.docker.com/r/enarciso/immich-machine-learning |
Beta Was this translation helpful? Give feedback.
-
|
@enarciso are you planning to open a PR to bring this feature to Immich? I would love to use S3 storage, but on the other hand I would keep my setup running on the official images |
Beta Was this translation helpful? Give feedback.
-
I would love to, although I feel like I'm breaking some core architectural principles with this approach (not sure). I'm literally shimming it in However, I understand your point, so I'll research it further and see what I come up with. Thanks |
Beta Was this translation helpful? Give feedback.
-
|
@enarciso I'd just open the PR and get on with the feedback. You could always submit the review/feedback from the PR to the LLM, and make it update accordingly anyways 😏 |
Beta Was this translation helpful? Give feedback.
-
|
I have two immich storage paths. One for thumbnails etc which is stored on SSD and one where the original files is stored on HDD. I have also 2 different minio instances. One on SSD and one on HDD. Would it be possible to define here 2 S3 endpoints and bucket? |
Beta Was this translation helpful? Give feedback.
-
The worst that can happen is they say it cannot be merged this way, and give you some guidance on how it could be improved - if you don't have the time, others might help finishing it. The best scenario is everyone having an official S3 support in the near future. I think you can give it a try |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure what happened to my last comment here, but I did submit a PR, and it was a no, as I expected. #22427 |
Beta Was this translation helpful? Give feedback.
-
|
I am doing a little experiment with S3Backer to indirectly use object storage, but it still requires testing to see how stable it is. If you want to give it a try and test it, while waiting for the feature to be implemented, you can find a guide on how I made it at this link: https://damianogiorgi.it/articles/2025/11/my-cheap-aws-setup-to-host-immich-files-on-s3/ |
Beta Was this translation helpful? Give feedback.
This comment was marked as duplicate.
This comment was marked as duplicate.
-
|
I would definitely love Immich supporting native S3 object storage. In the meantime, I enjoyed the technical challenge of getting S3 object storage working. Happy new year! https://gvolpe.com/blog/immich-photos/ Immich is awesome 🤩 |
Beta Was this translation helpful? Give feedback.
-
|
I've been following this discussion and #1683 for a while, and wanted to offer a perspective as a user and self-hosting advocate — not as a coder. I haven't implemented what I'm describing, and I don't know if it's entirely feasible. But I think there may be a disconnect between the concerns raised and the use cases driving demand for S3 support, and I wanted to try to articulate it. The S3 support being discussed here appears to focus on server-proxied object storage — Immich stores files in S3 but still acts as an intermediary for all uploads and downloads. This addresses storage flexibility, data resilience, and decouples storage capacity from the server's local disk. All valuable things and I am not downtalking any of these. However, I'd gently suggest this architecture doesn't address what may be the primary barrier to a broader adoption in my opinion: the Immich server becoming a bandwidth bottleneck. Consider a typical self-hosting scenario: someone runs Immich on a modest VPS or home server with limited upload bandwidth. When family members back up photos or browse their library, every byte flows through that server. The experience is constrained by the server's connection, not by the user's connection or the storage provider's capabilities. The architecture that would be transformative — and what I believe services like Ente Photos implement — is direct client-to-storage transfers:
In this model, the Immich server handles authentication, metadata, ML processing, and orchestration — but bulk data transfer bypasses the server entirely. A user downloading a 4K video gets the speed of their connection to the S3 provider, not their connection to someone's residential upload pipe or a cheap VPS. I noticed @uhthomas raised concerns about pre-signed URLs earlier in #1683, and I wanted to engage with those directly, because I suspect we may be imagining different use cases: On caching and unfriendly URLs: In the architecture I'm imagining, pre-signed URLs wouldn't be exposed to users or cached long-term. The Immich client would request an asset, the server would generate a short-lived pre-signed URL on demand (based on its own caching logic), and redirect the client. The URL expires in minutes — it's not something users bookmark or share. The caching and UX concerns seem to apply to a different pattern where pre-signed URLs are stored or handed out in advance. On S3 not being publicly accessible: This concern feels disconnected from the use cases driving most of the demand in these threads. The people asking for S3 support are largely saying things like:
For these use cases, the S3 bucket is definitionally publicly accessible — that's the whole point. If someone is running MinIO locally on the same network as Immich, they're not really decoupling compute from storage, and local filesystem storage would serve them just as well. I realize I may be missing technical constraints that make this harder than it sounds. But I wanted to name this distinction clearly, because server-proxied S3 — while useful — doesn't fundamentally change the scalability story for users who want to serve a distributed family from limited infrastructure. Direct client-to-storage is what decouples compute from storage in a way that meaningfully impacts adoption. If this architecture is already on the roadmap and I've misread the discussion, I apologize for the noise. And if there are fundamental reasons it won't work, I'd genuinely love to understand them. Appreciate all the work going into this. |
Beta Was this translation helpful? Give feedback.
-
|
I built a proof-of-concept that adds S3-compatible object storage as an alternative backend to Immich's local disk storage. Both backends work simultaneously - existing disk assets keep working while new uploads go to S3. What works:
How it works:
If there's interest from the maintainers, I'm happy to clean this up, address feedback, and submit a PR. The implementation is designed to be non-breaking. Disk mode is the default and behaves identically to today. https://github.com/Deeds67/immich 2026-03-03.18-23-24.mp4 |
Beta Was this translation helpful? Give feedback.
-
|
Probably a very silly question, but what are the current discussion in the core team? Is this still an active topic? Is it being actively planned? Are there any rough target dates? Thanks for the awesome product, it's very much appreciated. |
Beta Was this translation helpful? Give feedback.
-
|
@Deeds67 I just saw you committing to this immich fork named gallery: https://github.com/open-noodle/gallery which seems to be exactly what I have been seeking, namely, the S3 Compatible Storage section reads as follows:
Who is behind this fork and for how long has it been around? I am be very excited and eager to test it and hopefully switch to it in the near future. PS: If this is your fork then I would like to support you, please let me know how you would like to be supported. |
Beta Was this translation helpful? Give feedback.
-
|
With all due respect to the maintainers opinions/prioritizes etc, I’d like to add a reflection from my own usage. My personal library is multi-terabyte and even though I would very much like to move it from NAS to cloud, the SSD option is just too expensive. I’m also hoping to help two non-profits with large archives migrate to Immich at some point. Their archives are already in the tens of TB and yearly cloud storage costs is in the thousands. This is already unsustainable for them and it will just keep growing. IMHO, even at what might be considered “moderate” library sizes today, block storage becomes tricky, monthly costs are normally multiple times higher compared to object storage, and the gap grows as the archive expands. Beyond cost, traditional storage normally requires tracking usage and manually scaling, which is a real concern. What I am trying to say is that many users naturally accumulate multi-TB archives over time, and this is hard to scale well with cloud based SSD-based storage. S3 support could make things more sustainable long term. Just my two cents, huge fan either way. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Object storage support has been widely requested (#1683) and is something we're keen to support. The limitations imposed by object storage happen to be beneficial for data resilience and consistency, as it makes features like the storage template infeasible. Issues like orphaned assets (#2877) or asset availability (#4442) would be resolved completely.
As discussed on the orphaned assets issue (#2877), I'd like to propose a new storage layout designed for object storage, with scalability and resilience as priorities.
Where:
<asset id>is a unique ID for an asset, ideally a random UUID. UUIDv7 may serve to be beneficial due to its property of natural order. If not, UUIDv4 should be sufficient.<original asset filename>is the original filename of an asset, as it was uploaded.The above structure should serve to efficiently scale with resiliency and flexibility. The unique 'directory' for an asset can contain additional files like edits, colour profiles, thumbnails or anything else.
The original file and filename is preserved in case of an unlikely full database loss, where it should be possible to restore most information in such a scenario. This property is also good for humans, or if a full export is required. A directory of vague filenames without extensions would be quite unhelpful. I feel this strikes a good balance between legibility and a resiliency.
I have also considered content addressable storage (CAD), as it would save space in the event of duplicate uploads but consider it to be impractical due to complexity and the previous concern of legibility. I believe this should instead be deferred to the underlying storage provider, which can make much better decisions about how to store opaque binary blobs.
Part of this effort will require some changes to the storage interfaces (#1011) and the actual object storage implementation should use the AWS S3 SDK (docs). Most, if not all object storage systems should have an S3-compatible API.
Beta Was this translation helpful? Give feedback.
All reactions