This document provides detailed instructions for installing LightNVR on various platforms.
- Prerequisites
- Installation Methods
- Platform-Specific Instructions
- Post-Installation Setup
- Upgrading
- Uninstallation
Before installing LightNVR, ensure your system meets the following requirements:
- Processor: Any Linux-compatible processor (ARM, x86, MIPS, etc.)
- Memory: 256 MB minimum; 1 GB or more if you enable object detection — see below
- Storage: Any storage device accessible by the OS, sized for your retention policy
- Network: Ethernet or WiFi connection
- OS: Linux with kernel 4.4 or newer
LightNVR is built for memory-constrained hardware, so the floor is low, but "minimum" and "enough for your setup" are different numbers.
| Deployment | Memory |
|---|---|
| Container, started, no streams configured | ~75 MB measured (LightNVR ~33 MB, go2rtc ~16 MB) |
| A few streams, recording only, no detection | 256 MB is workable |
| Object detection enabled | 1 GB or more — models are held in memory |
| Many streams, or detection across several streams | 2 GB and up |
The idle figure is measured from the published amd64 image on first start with no
cameras. Everything above it scales with what you actually run: each stream costs buffers
([memory] buffer_size, 1024 KB per stream by default) plus whatever the decoder needs for
that resolution, and object detection adds the model's working set on top.
If you are sizing a box rather than checking a floor: recording alone is cheap and mostly I/O-bound, while detection is what will decide your RAM. A swap file is supported and helps small devices survive spikes, but do not plan to run detection out of swap.
Most installations should use the container image, a
pre-built .deb package, or the Home Assistant add-on.
Build from source for development, for embedded targets, or for an OS release without a
package.
git clone https://github.com/opensensor/lightnvr.git
cd lightnvr
# Initialize submodules (required for go2rtc)
git submodule update --init --recursiveLightNVR 0.48.x requires the pinned OpenSensor go2rtc fork for live view. A
stock upstream go2rtc binary does not acknowledge LightNVR's media policy.
Build the submodule with ./scripts/install_go2rtc.sh (requires Go), or set
[go2rtc] binary_path to your own build of the pinned submodule. The installer
never falls back to an upstream binary.
For an ARMv7 cross-build, run ./scripts/install_go2rtc.sh --arch armv7l --install-dir "$PWD/staging/bin" --config-dir "$PWD/staging/go2rtc" on a Go
build host, then copy the staged binary to the device.
See the Platform-Specific Instructions section for dependency installation commands for your distribution.
# Build in debug mode (default)
./scripts/build.sh
# Or build in release mode (recommended for production)
./scripts/build.sh --release# Install (requires root privileges)
sudo ./scripts/install.shThe installation script will:
- Install the binary to
/usr/local/bin/lightnvr - Install configuration files to
/etc/lightnvr/ - Create data directories in
/var/lib/lightnvr/ - Create a systemd service file
You can customize the installation paths using options:
sudo ./scripts/install.sh --prefix=/opt --config-dir=/etc/custom/lightnvrSee ./scripts/install.sh --help for all available options.
Direct CMake installs also default to /etc/lightnvr, matching the runtime
config search path and service configuration. This default is independent of
CMAKE_INSTALL_PREFIX and cmake --install --prefix. Packagers can stage the
layout without writing to the host's /etc:
DESTDIR="$PWD/package-root" cmake --install buildTo opt into a relocatable layout, set CMAKE_INSTALL_SYSCONFDIR to a relative
directory. For example:
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/lightnvr -DCMAKE_INSTALL_SYSCONFDIR=etc
cmake --build build
sudo cmake --install buildThis installs configuration to /opt/lightnvr/etc/lightnvr; start LightNVR with
-c /opt/lightnvr/etc/lightnvr/lightnvr.ini. Relative sysconf directories follow
cmake --install --prefix; absolute overrides such as /etc/custom do not.
CMake installs binaries, configuration files and migrations; it does not perform
the service/data-directory setup provided by scripts/install.sh.
Docker provides an easy way to run LightNVR without installing dependencies directly on your system.
Docker Compose simplifies the deployment and ensures proper volume configuration.
# Clone the repository
git clone https://github.com/opensensor/lightNVR.git
cd lightNVR
# Prepare the recordings bind mount for the image's non-root UID:GID
sudo install -d -o 10001 -g 10001 -m 0750 ./data/recordings
# Start the container from the published image
docker compose up -dThe default docker-compose.yml persists storage in three named volumes and one host directory:
lightnvr-config— configuration at/etc/lightnvrlightnvr-database— database at/var/lib/lightnvr/data/databaselightnvr-models— models at/var/lib/lightnvr/data/models./data/recordings— recordings at/var/lib/lightnvr/data/recordings
Compose prefixes named volumes with its project name. If reusing a recordings directory, ensure UID:GID 10001:10001 can write it.
To customize the configuration:
# Copy the initialized configuration to a private local file
umask 077
docker compose cp lightnvr:/etc/lightnvr/lightnvr.ini ./lightnvr.ini
nano ./lightnvr.ini
# Write it back as the container user to preserve volume ownership
docker compose exec -T lightnvr sh -c 'cat > /etc/lightnvr/lightnvr.ini' < ./lightnvr.ini
# Restart the container to apply changes
docker compose restartdocker pull ghcr.io/opensensor/lightnvr:latestdocker volume create lightnvr-config
docker volume create lightnvr-database
docker volume create lightnvr-recordings
docker volume create lightnvr-modelsThese volumes preserve configuration, database, recordings, and models when the container is replaced. New empty volumes inherit the image's directory ownership for its non-root user.
docker run -d \
--name lightnvr \
--restart unless-stopped \
-p 8080:8080 \
--security-opt no-new-privileges --cap-drop ALL \
-v lightnvr-config:/etc/lightnvr \
-v lightnvr-database:/var/lib/lightnvr/data/database \
-v lightnvr-recordings:/var/lib/lightnvr/data/recordings \
-v lightnvr-models:/var/lib/lightnvr/data/models \
ghcr.io/opensensor/lightnvr:latest# Copy to a private local file and edit it
umask 077
docker cp lightnvr:/etc/lightnvr/lightnvr.ini ./lightnvr.ini
nano ./lightnvr.ini
# Write it back as the container user to preserve volume ownership
docker exec -i lightnvr sh -c 'cat > /etc/lightnvr/lightnvr.ini' < ./lightnvr.iniNote: Ensure the paths in lightnvr.ini point to /var/lib/lightnvr/data subdirectories:
- Database:
/var/lib/lightnvr/data/database/lightnvr.db - Recordings:
/var/lib/lightnvr/data/recordings - MP4 recordings:
/var/lib/lightnvr/data/recordings/mp4 - Models:
/var/lib/lightnvr/data/models
docker restart lightnvrPre-built packages are available from GitHub Releases.
Visit the LightNVR Releases page and
download the package matching both your architecture and your Debian suite. Assets are
named lightnvr_<version>_<suite>_<arch>.deb, for example:
lightnvr_0.47.2_trixie_arm64.deb # Debian 13 / Raspberry Pi OS (trixie), 64-bit
lightnvr_0.47.2_sid_amd64.deb # Debian unstable, x86-64
lightnvr_0.47.2_trixie_armhf.deb # 32-bit ARM
The suite matters: the packages link against that release's system libraries, so a sid
package on a trixie system will fail to satisfy its dependencies.
From 0.47.3, each release also carries lightnvr-rs_<version>_sid_amd64.deb, the build
generated from the same C sources as Rust (see rust/README.md). Install
one package or the other, not both.
# Substitute the version, suite and architecture you need
wget https://github.com/opensensor/lightNVR/releases/download/0.47.2/lightnvr_0.47.2_trixie_arm64.deb
# Install the package
sudo dpkg -i lightnvr_0.47.2_trixie_arm64.deb
# Install any missing dependencies
sudo apt-get install -fOnly .deb packages are published. On non-Debian systems, use
the container or build from source.
sudo apt-get update
sudo apt-get install -y \
build-essential \
cmake \
pkg-config \
git \
libsqlite3-dev \
libavcodec-dev \
libavformat-dev \
libavutil-dev \
libswscale-dev \
libavfilter-dev \
libuv1-dev \
libcurl4-openssl-dev \
libmbedtls-dev \
curl \
wgetNote: libuv1-dev is required for the HTTP server. libmbedtls-dev is required for ONVIF support and authentication system (cryptographic functions). llhttp is downloaded and built automatically by CMake if not found.
sudo dnf install -y \
gcc \
gcc-c++ \
make \
cmake \
pkgconfig \
git \
sqlite-devel \
ffmpeg-devel \
libuv-devel \
libcurl-devel \
mbedtls-devel \
curl \
wgetNote: libuv-devel is required for the HTTP server. mbedtls-devel is required for ONVIF support and authentication system (cryptographic functions).
sudo pacman -S \
base-devel \
cmake \
git \
sqlite \
ffmpeg \
libuv \
curl \
wget \
mbedtlsNote: libuv is required for the HTTP server. mbedtls is required for ONVIF support and authentication system (cryptographic functions).
The Ingenic A1 SoC requires cross-compilation. A detailed guide is provided below.
# Download and extract the toolchain
wget https://github.com/Ingenic-community/mips-linux-toolchain/releases/download/latest/mips-linux-uclibc-toolchain.tar.gz
sudo mkdir -p /opt/mips-linux-toolchain
sudo tar -xzf mips-linux-uclibc-toolchain.tar.gz -C /opt/mips-linux-toolchain# Install build tools
sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config
# Clone and build cross-compiled dependencies
git clone https://github.com/lightnvr/ingenic-dependencies.git
cd ingenic-dependencies
./build-all.sh# Clone the repository
git clone https://github.com/opensensor/lightnvr.git
cd lightnvr
# Initialize submodules (required for go2rtc)
git submodule update --init --recursive
# Cross-compile by pointing the build at a CMake toolchain file
CMAKE_TOOLCHAIN_FILE=/path/to/your/mips-ingenic.cmake ./scripts/build.sh --releasescripts/build.sh passes CMAKE_TOOLCHAIN_FILE straight through to CMake, which is how
all cross-compilation is driven. The repository ships
cmake/toolchains/armv7-linux-gnueabihf.cmake as a working example; there is no MIPS
toolchain file in-repo, so for Ingenic you supply one pointing at the toolchain you
extracted above.
The binary lands at build/Release/bin/lightnvr.
# Copy the binary and configuration files to the device
scp build/Release/bin/lightnvr root@ingenic-device:/usr/local/bin/
scp config/lightnvr.ini root@ingenic-device:/etc/lightnvr/lightnvr.ini
# Create necessary directories on the device
ssh root@ingenic-device "mkdir -p /var/lib/lightnvr/data/recordings /var/lib/lightnvr/www /var/log/lightnvr"
# Copy the *built* web interface (web/ holds sources; web/dist/ is what gets served)
cd web && npm ci && npm run build && cd ..
scp -r web/dist/* root@ingenic-device:/var/lib/lightnvr/www/Raspberry Pi is a Debian system, so everything in the Debian/Ubuntu section applies. In order of least to most effort:
- Container —
ghcr.io/opensensor/lightnvrpublishesarm64andarm/v7. See DOCKER.md. This is the path most Pi users want. .debpackage — prebuilt forarm64andarmhfon the Releases page, for both Debian trixie (stable) and sid. Match the package to your OS release, not just the architecture.- From source — below. Worth it if you are developing, or on an OS release we do not package for.
This is the mistake that kills Pi NVR builds. Continuous video writing will wear out a microSD card, and when it fails it usually takes the SQLite database with it. Put recordings — and ideally the whole data directory — on a USB SSD or HDD:
[storage]
path = /mnt/ssd/lightnvr/recordings
[database]
path = /mnt/ssd/lightnvr/database/lightnvr.dbMake sure the drive is mounted at boot (an /etc/fstab entry, not a desktop automount)
before pointing LightNVR at it, or the service will start against an empty mount point.
A Pi 4 or 5 with 2 GB or more handles several streams comfortably. A Pi Zero or a first-generation model will struggle with anything beyond one low-resolution stream. Object detection wants 1 GB of headroom on top of whatever your streams use — see Memory in practice.
Prefer a 64-bit OS. arm/v7 builds exist, but 32-bit ARM is the least-tested target and
Home Assistant has already dropped it.
sudo apt-get update
sudo apt-get install -y \
build-essential \
cmake \
pkg-config \
git \
libsqlite3-dev \
libavcodec-dev \
libavformat-dev \
libavutil-dev \
libswscale-dev \
libavfilter-dev \
libuv1-dev \
libcurl4-openssl-dev \
libmbedtls-dev \
curl \
wgetNote: libuv1-dev is required for the HTTP server. libmbedtls-dev is required for ONVIF support and authentication system (cryptographic functions).
# Clone the repository
git clone https://github.com/opensensor/lightnvr.git
cd lightnvr
# Initialize submodules (required for go2rtc)
git submodule update --init --recursive
# Build (ARM architecture is detected automatically)
./scripts/build.sh --release
# Install
sudo ./scripts/install.shA NAS is a natural home for an NVR — it already has the disks. All of these run Docker under their own branding (Synology Container Manager, QNAP Container Station, unRAID Docker tab, TrueNAS SCALE Apps), so DOCKER.md is the reference and their own documentation covers the click-path for adding a container.
Four things are LightNVR-specific and are what people actually get wrong:
Do not put the database on a network share. Recordings on a share are fine; the SQLite
database is not. NFS and SMB do not implement the file locking SQLite expects, and the
result is corruption rather than an error message. Keep [database] path on local storage
— the same volume the container runs from — and point only [storage] path at the big
array. This applies to the NAS's own shares mounted back into the container, not just
remote ones.
Bridge networking breaks ONVIF discovery. WS-Discovery is multicast and will not cross
the default bridge. Either set LIGHTNVR_ONVIF_NETWORK to your camera subnet in CIDR form
(the unicast sweep works through NAT), or give the container host/macvlan networking, which
most NAS UIs expose. Host networking also makes WebRTC live view work without extra port
mapping.
Check the UID the container runs as. These platforms often run containers as a non-root user of their choosing. The data directory must be writable by whatever that is, or LightNVR will start and then fail to record.
Mind the spin-down. If the array parks its disks, continuous recording will keep waking them, and event-triggered recording will lose the first seconds to spin-up latency. Either disable spin-down for the recording volume or accept the trade.
Ports and volumes are identical to any other Docker deployment: map /etc/lightnvr and
/var/lib/lightnvr/data, never /var/lib/lightnvr itself.
On Home Assistant OS or Supervised, install LightNVR from the Add-on Store by adding the
repository https://github.com/opensensor/lightnvr-hassio-addons.
See LightNVR on Home Assistant for the walkthrough and for the ways the add-on differs from a plain Docker deployment — it serves the web UI on port 7800, uses host networking, and keeps recordings out of your Home Assistant backups.
Home Assistant Container and Core installs have no add-on store; use DOCKER.md there.
LightNVR is Linux software; there is no native Windows build and none is planned. On Windows you run the published Linux container.
See Running LightNVR on Windows with Podman + WSL2 for the full
walkthrough, including the Windows-specific parts that are easy to get wrong: reaching the
web UI from other devices on your LAN, why the database must not live on a C:\ path, and
what it takes to keep a recorder running through sleep and reboots.
Docker Desktop works too, and DOCKER.md applies unchanged if you prefer it.
After installing LightNVR, follow these steps to complete the setup:
Edit the configuration file:
sudo nano /etc/lightnvr/lightnvr.iniAt minimum, you should:
- Set a secure password for the web interface
- Configure storage paths
- Set up your camera streams
See CONFIGURATION.md for detailed configuration options.
# Start the service
sudo systemctl start lightnvr
# Enable the service to start at boot
sudo systemctl enable lightnvrsudo systemctl status lightnvrOpen a web browser and navigate to:
http://your-device-ip:8080
Log in with the username and password configured in the configuration file.
# Navigate to the repository
cd lightnvr
# Pull the latest changes
git pull
# Update submodules to the revisions required by the new commit
git submodule update --init --recursive
# Rebuild
./scripts/build.sh --release
# Stop the service
sudo systemctl stop lightnvr
# Install the new version
sudo ./scripts/install.sh
# Start the service
sudo systemctl start lightnvrThe default Compose file uses the published image:
# Navigate to the repository
cd lightNVR
# Pull the latest changes
git pull
# Pull latest image and restart
docker compose pull
docker compose up -dIf you enabled the commented build: configuration instead of image:, update
the source and submodules, then rebuild before recreating the service:
git pull
git submodule update --init --recursive
docker compose build --pull
docker compose up -d# Pull the latest image
docker pull ghcr.io/opensensor/lightnvr:latest
# Stop and remove the container
docker stop lightnvr
docker rm lightnvr
# Run a new container with the latest image
docker run -d \
--name lightnvr \
--restart unless-stopped \
-p 8080:8080 \
--security-opt no-new-privileges --cap-drop ALL \
-v lightnvr-config:/etc/lightnvr \
-v lightnvr-database:/var/lib/lightnvr/data/database \
-v lightnvr-recordings:/var/lib/lightnvr/data/recordings \
-v lightnvr-models:/var/lib/lightnvr/data/models \
ghcr.io/opensensor/lightnvr:latestNote: Your data is preserved in the volumes, so upgrading will not affect your database or recordings.
# Stop the service
sudo systemctl stop lightnvr
sudo systemctl disable lightnvr
# Remove the service file
sudo rm /etc/systemd/system/lightnvr.service
sudo systemctl daemon-reload
# Remove the binaries and migrations (default install paths)
sudo rm -f /usr/local/bin/lightnvr /usr/local/bin/lightnvr-ffmpeg-guard
sudo rm -rf /usr/local/share/lightnvr/migrations
# Remove configuration and data (optional, default paths)
sudo rm -rf /etc/lightnvr
sudo rm -rf /var/lib/lightnvr
sudo rm -rf /var/log/lightnvrNote: If you installed with a custom --prefix or custom config/data/log
directories, replace the paths above with the exact paths you chose during
installation. The optional data removal also removes the installed web assets
under the data directory. Separately installed go2rtc binaries and shared SOD
libraries may have other consumers; remove them only if no other installation
uses them.
# Navigate to the repository
cd lightNVR
# Stop and remove the container
docker compose down
# Remove the image
docker rmi ghcr.io/opensensor/lightnvr:latest
# Delete configuration, database, and models (optional; irreversible)
docker compose down --volumes
# Delete recordings in the bind mount separately (optional; irreversible)
sudo rm -rf ./data/recordings# Stop and remove the container
docker stop lightnvr
docker rm lightnvr
# Remove the image
docker rmi ghcr.io/opensensor/lightnvr:latest
# Remove named volumes (optional - this will delete all data)
docker volume rm lightnvr-config
docker volume rm lightnvr-database
docker volume rm lightnvr-recordings
docker volume rm lightnvr-models