This reference lists essential commands to monitor Immich performance on Ubuntu, including CPU, RAM, disk I/O, Docker containers, and NVIDIA GPU usage.
Immich Performance Monitoring Commands
This reference lists essential commands to monitor Immich performance on Ubuntu, including CPU, RAM, disk I/O, Docker containers, and NVIDIA GPU usage.
1. System-Wide CPU & RAM Monitoring
| Command |
Description |
top |
Live CPU, RAM, and process overview. |
htop |
Improved interactive system monitor (install with sudo apt install htop). |
vmstat 1 |
Shows CPU, memory, and I/O every second. |
mpstat -P ALL 1 |
Per‑core CPU usage every second. |
free -h |
Human-readable RAM usage. |
iostat -x 1 |
Disk I/O performance (install with sudo apt install sysstat). |
# Install tools
sudo apt update
sudo apt install htop sysstat
2. Docker Container Performance (Immich Services)
| Command |
Description |
docker stats |
Live CPU, RAM, and network usage for all containers. |
docker stats immich_machine_learning |
Monitor only the ML/OCR container. |
docker top immich_machine_learning |
Show processes running inside the ML container. |
docker logs -f immich_machine_learning |
Live OCR logs (useful for throughput). |
docker inspect immich_machine_learning |
Detailed container info (CPU limits, mounts, etc.). |
# See all Immich containers
docker ps | grep immich
3. Immich Machine-Learning (OCR) Throughput
| Command |
Description |
docker logs -f immich_machine_learning |
Shows OCR jobs being processed in real time. |
grep -i ocr /var/lib/docker/containers/*/*.log |
Search for OCR-related logs across containers. |
journalctl -u docker –since "10 min ago" |
Check recent OCR activity via Docker logs. |
# Count OCR jobs processed in the last minute
docker logs immich_machine_learning 2>&1 | grep -i "ocr" | tail -n 50
4. NVIDIA GPU Monitoring (If Immich Uses GPU)
| Command |
Description |
nvidia-smi |
Shows GPU usage, VRAM, temperature, and running processes. |
watch -n 1 nvidia-smi |
Live GPU monitoring every second. |
nvidia-smi dmon |
GPU utilization, memory, and power draw in real time. |
nvidia-smi pmon -c 1 |
Per-process GPU usage. |
# Check if Immich ML container is using the GPU
nvidia-smi | grep immich
5. Network & Disk Performance (Useful for Immich Uploads)
| Command |
Description |
iftop |
Live network usage per connection (install with sudo apt install iftop). |
nload |
Simple live network throughput monitor. |
iotop |
Live disk I/O per process (install with sudo apt install iotop). |
# Install network/disk tools
sudo apt install iftop nload iotop
6. Combined Monitoring (Recommended)
# CPU + RAM + processes
htop
# GPU + Immich ML container
watch -n 1 nvidia-smi
# Docker container performance
docker stats
# Disk I/O
iotop
# Network throughput
nload
7. Immich-Specific Health Checks
| Command |
Description |
docker logs immich_server |
Check server performance issues. |
docker logs immich_machine_learning |
Check OCR/ML performance. |
docker logs immich_microservices |
Check background job performance. |
docker stats | grep immich |
Monitor all Immich containers at once. |
