A few weeks ago I set myself a challenge: run Immich — a full self-hosted photo management platform — natively on my Android phone, without Docker, without root, and without any cloud dependency.
The result is immich-native-android, a working port for Android/Termux on aarch64. This is what it took to get there.
Why this is not trivial
Immich is designed to run on Linux servers via Docker. It's a multi-service stack: PostgreSQL, Redis, a Node.js server, and a Python ML service for face recognition and smart search.
Android is not Linux. The differences that matter:
Bionic libc instead of glibc — most prebuilt native binaries simply crash or silently fail
No FUSE without root — you can't mount remote filesystems as local paths
No systemd — no service manager, no socket activation
Phantom Process Killer — Android 12+ aggressively kills background processes
Read-only /tmp — many build systems assume they can write there
No FHS layout — paths like/usr/bindon't exist in Termux
Every single one of these required a workaround.
The architecture
proot Debian (container)
└── PostgreSQL 17 + VectorChord extension
↓ localhost:5432
Termux (native aarch64)
├── Redis
├── Node.js 20 → Immich server (port 2283)
└── Python + ONNX → Immich ML (port 3003)
PostgreSQL runs inside a proot Debian container because it needs glibc and kernel features unavailable in Termux. Everything else runs natively.
The problems, one by one
1. Node.js version
The latest Node.js caused silent startup failures on Bionic. The fix was pinning to Node 20 LTS and forcing npm to treat the platform as Linux:
npm_config_platform=linux
npm_config_arch=arm64
npm_config_libc=glibc
This tricks Sharp and other native modules into using their linux-arm64 prebuilts instead of trying (and failing) to detect Android.
2. Native dependencies
Most npm packages ship prebuilt binaries compiled against glibc. On Bionic they either crash immediately or produce silent errors.
Sharp (image processing) required full recompilation from source against Termux's libvips:
SHARP_FORCE_GLOBAL_LIBVIPS=1
bcrypt — same treatment, rebuilt from source.
Python ML dependencies (ONNX Runtime, InsightFace) had no Android/aarch64 wheels at all. Each was compiled inside a Python venv using uv and Rust-based build tools:
uv sync --python-platform manylinux_2_28_aarch64
watchfiles was removed entirely — it requires maturin (a Rust build tool) that doesn't work on Android's Bionic.
Other fixes that were necessary across the build:
NODE_OPTIONS=--max-old-space-size=6144 # prevents OOM during build
TMPDIR=$HOME/tmp # /tmp is read-only on Android
npm_config_script_shell=$(which bash) # install scripts need bash, not sh
3. PostgreSQL in proot
PostgreSQL cannot run natively in Termux — it needs glibc and kernel features that Android doesn't provide. The solution: run it inside a proot Debian container.
The catch: PostgreSQL crashes when started as root inside proot. The fix was creating a dedicated postgres user inside the container and launching the service under that user via a scripted proot session.
4. WebDAV external library — patching Immich source
This was the most complex problem.
The goal: index photos stored on a remote NAS without copying them to the phone.
The problem: Android has no FUSE support without root, so you can't mount a network share as a local path. The only Android solution (RSAF) exposes files through the Storage Access Framework — completely inaccessible from Termux.
The solution: patch Immich's source code before building.
Immich's LibraryService validates external library paths with path.isAbsolute(), which rejects HTTP URLs. I added bypass logic for WebDAV paths before the TypeScript compilation step:
if (importPath.startsWith('http://')) {
// WebDAV path — skip isAbsolute() check
}
The NAS phone runs rclone serve webdav over Tailscale. Immich indexes the photos without ever copying them locally.
5. Phantom Process Killer
Android 12+ kills background processes not started by the foreground app. Immich runs as four separate processes (PostgreSQL, Redis, Node, Python). Without intervention, Android kills them within minutes.
Fix via Shizuku + ADB (run once after each reboot):
adb shell device_config set_sync_disabled_for_tests persistent
adb shell device_config put activity_manager max_phantom_processes 2147483647
What works
- Full Immich web UI on
localhost:2283
- Photo/video upload and backup
- Album management
- External library indexing via WebDAV (remote NAS, no local copy)
- Thumbnail generation
- Timeline and map view
- Machine learning (face recognition, CLIP smart search) — works on this setup, stability may vary
What doesn't (yet)
- No GPU/NPU acceleration — all ML runs on CPU
- Immich updates require re-running the install script
- Shizuku must be re-enabled after each reboot
Tested on
Samsung Galaxy S25 — Snapdragon 8 Elite, aarch64, Android 15
Immich v2.5.6
The repo
Everything is documented and scripted:
👉 github.com/Gennyi07/immich-native-android
Based on arter97/immich-native, heavily reworked for Android/Bionic.
If you find it useful, a ⭐ on GitHub helps the project get discovered.
Final thought
The Android/Bionic compatibility layer is genuinely hostile to software not designed for it. Every layer of this stack required a workaround. But it works — and it runs on hardware most people already own.
If you've been looking for a way to run Immich without a dedicated server, this might be it.