Make content streamed from NZBDAV available permanently.

Persistarr is a lightweight command-line service that monitors content streamed via your NZBDAV server. When content is streamed by users, Persistarr automatically saves the streamed content to permanent storage. This content will then be available locally as regular files in the media library after the first user streamed it and will not need to be re-downloaded for subsequent access.

With Persistarr, you can have the best of both worlds: fast streaming from NZBDAV for immediate initial access without downloading first, while retaining permanent local copies of your streamed media for future use.

• Monitoring: Continuously monitors your library for NZBDAV streaming activity.
• Automatic Saving: Automatically saves streamed content to permanent storage so it remains available for future access.
• Configurable: Persistarr checks how much of each file has been streamed and saves it once a configurable threshold is reached (default is 75%). File patterns can be used to only include certain types of files.

This guide assumes you already have NZBDAV set up and running according to the guide.

Important: NZBDAV must be configured to use the rclone sidecar feature for Persistarr to save files, even if you are using STRM-compatible media libraries (Jellyfin/Emby).

Persistarr leverages the cache that rclone creates when streaming files from NZBDAV to persist files once they have been sufficiently streamed. You can keep your existing NZBDAV docker-compose configuration unchanged:

  nzbdav:
    image: nzbdav/nzbdav:latest
    container_name: nzbdav
    restart: unless-stopped
    volumes:
      - '/config/nzbdav:/config'
      - '/mnt:/mnt' # Directory containing mount points
    ...

We need to adjust the rclone configuration used by NZBDAV to ensure that content is being cached locally. We add a dedicated cache mount point for rclone and configure the caching parameters accordingly. Make sure to create this cache directory on your host system and set appropriate permissions so that the rclone container can write to it (adjust cache location to your preferences).

mkdir -p /data/usenet-stream/cache
chown 1000:1000 /data/usenet-stream/cache

Then update the rclone service in your docker-compose file as follows:

  nzbdav_rclone:
    image: rclone/rclone:latest
    container_name: nzbdav_rclone
    restart: unless-stopped
    volumes:
      - '/mnt:/mnt:rshared'                                              # Directory containing mount points
      - '/data/usenet-stream/cache:/data/usenet-stream/cache'            # ADDED CACHE DIRECTORY
      - '/config/nzbdav/rclone.conf:/config/rclone/rclone.conf'
    ...
    command: >
      mount nzbdav: /mnt/remote/nzbdav                    # The actual webdav mount point
        --uid=1000
        --gid=1000
        --allow-other
        --links
        --use-cookies
        --cache-dir="/data/usenet-stream/cache"      # ADD: USE SPECIFIED CACHE DIRECTORY
        --vfs-cache-mode=full
        --vfs-cache-max-size=150G                    # Configure max cache size and age as needed
        --vfs-cache-max-age=365d                     # Should be set high enough to retain streamed content until Persistarr saves it
        --buffer-size=0M
        --vfs-read-ahead=512M
        --dir-cache-time=20s

Take note of both the actual webdav mount point provided to the mount command (here /mnt/remote/nzbdav, note the included remote/nzbdav rather than just /mnt) and the rclone cache directory (here /data/usenet-stream/cache).

  persistarr:
    image: ghcr.io/persistarr/persistarr:latest
    container_name: persistarr
    user: 1000:1000
    environment:
      - TZ=${TZ}
    volumes:
      - '/config/persistarr:/config'                                    # Your local config directory
      - '/mnt:/mnt:rshared'                                             # Directory containing mount points
      - '/data/media:/data/media'                                       # Your media library root directory
      - '/data/usenet-stream/cache:/data/usenet-stream/cache'           # Rclone cache directory
    command: >
      python3 persistarr.py -c /config/persistarr.conf daemon

All that remains is to configure Persistarr itself. Create the configuration file persistarr.conf in your local Persistarr config directory (/config/persistarr in the example above). There are three important paths that need to be configured correctly in the persistarr.conf file: the media library root, the rclone cache root, and the webdav mount root. The rest of the options control the behavior of Persistarr and can be adjusted as needed.

# Example configuration (you should adjust these paths to match your existing setup):

# The root directory of your Jellyfin/Emby/Plex media library. This is where Radarr/Sonarr is configured to import the symlinks that NZBDAV creates to your library. Contains folders like "movies", "tv", etc. 
media_library_root = "/data/media"

# The root directory where rclone stores its cache files. This is specified in your rclone configuration for NZBDAV as the "cache-dir" parameter.
rclone_cache_root = "/data/usenet-stream/cache"

# The root directory where NZBDAV mounts the WebDAV remote. This is specified in your rclone configuration for NZBDAV as the mount point in the "rclone mount" command.
# It should also be visible in NZBDAV under Settings -> SABnzbd -> Rclone Mount Directory.
webdav_mount_root = "/mnt/remote/nzbdav"

# The file pattern to include when looking for symlinks in the media library. Defaults to considering all files as candidates. Uses Unix shell-style wildcards.
file_pattern = "*"

# How much of a file needs to be streamed before Persistarr saves it permanently (in percent). Any missing data will be downloaded automatically by Persistarr to complete the file.
percent_content_available = 75

# Whether to automatically delete the download from NZBDAV after the file has been saved permanently. 
# Important: For this to work when enabled, NZBDAV must be configured to allow deletions via WebDAV.
# In NZBDAV, go to Settings -> WebDAV -> Uncheck "Enforce Read-Only"
delete_from_nzbdav = false

# How often (in minutes) the Persistarr daemon scans the library when running in daemon mode.
daemon_interval_minutes = 60
# How long to wait (in seconds) after startup before the first scan when running in daemon mode to allow other services to start up first.
daemon_startup_delay_seconds = 180

# Set to true to simulate actions without making any changes to the filesystem for testing.
dry_run = false  

Make sure to adjust the paths to match your existing setup. Then run the following and watch it go:

docker-compose up -d persistarr && docker-compose logs -f persistarr
Recreating persistarr ... done
Attaching to persistarr
persistarr        | == Persistarr - 1.0.0 (running as 1000:1000) ==
persistarr        | Starting Persistarr daemon...
persistarr        | Delaying startup by 180 seconds...
persistarr        | Scanning stream library '/data/media' for NZBDAV symlinks...
persistarr        | File /data/media/movies/I Like To Move It Move It/I Like To Move It Move It.mp4: 0% cached 14MB/10GB
persistarr        | File /data/media/movies/Let Me Go/Let Me Go.mkv: 75% cached 7.5GB/10GB (persisting)
persistarr        | Persisting file /data/media/movies/Let Me Go/Let Me Go.mkv (total 10GB, will download approximately 2.5GB missing).
persistarr        | Persisting file: copied 6% (625MB/10GB)
persistarr        | Persisting file: copied 28% (2.8GB/10GB)
persistarr        | Persisting file: copied 47% (4.7GB/10GB)
persistarr        | Persisting file: copied 69% (7.0GB/10GB)
persistarr        | Persisting file: copied 92% (9.4GB/10GB)
persistarr        | Successfully persisted file /data/media/movies/Let Me Go/Let Me Go.mkv (10GB).
persistarr        | Removing entry corresponding to /data/media/movies/Let Me Go/Let Me Go.mkv from NZBDAV WebDAV mount...
persistarr        | Removing file /data/usenet-stream/remote/nzbdav/content/movies/Let Me Go/Let Me Go.mkv from NZBDAV WebDAV mount...
persistarr        | Removing empty directory /data/usenet-stream/remote/nzbdav/content/movies/Let Me Go from NZBDAV WebDAV mount...
persistarr        | Persisted 1/2 files in the stream library.
persistarr        | Next Persistarr scan at 2026-01-16 13:43:15.530556...

We welcome bug reports and pull requests directly on Github.

• The NZBDAV Project: Prerequisite for using Persistarr.
• Awesomearr: List of useful tools for managing media libraries. You will eventually run out of space, so consider using some of the tools listed there to help manage your disk usage.
• Rclone Documentation: For more information on rclone configuration options. Also see the documentation for VFS File Caching for details on the caching options used by NZBDAV.