Installation

BBC iPlayer requires a UK IP address. If you are outside the UK, you must use a VPN. See VPN Configuration for setup details.

Requirements

• Docker (any platform supporting Linux containers)
• A UK IP address (direct connection or VPN)
• Storage for downloads and configuration

Environment Variables

Variable	Default	Description
TZ	Europe/London	Timezone
PUID	1000	User ID for file ownership
PGID	1000	Group ID for file ownership
UMASK	002	File permission mask

See Configuration Reference for the full list of environment variables.

Volumes

Path	Purpose
/config	BoltDB database and application settings
/downloads	Download output directory

---

Unraid

Use the Community Applications XML template rather than the raw Docker CLI below.

• Template repo: https://github.com/Will-Luck/unraid-templates
• Direct template URL (paste into CA -> "Template URL"): https://raw.githubusercontent.com/Will-Luck/unraid-templates/main/iplayer-arr.xml

The template wires up all of the config paths, VPN variables, and the NET_ADMIN + net.ipv4.conf.all.src_valid_mark=1 flags that the container needs when VPN_ENABLED=true.

---

Docker CLI

Basic (No VPN)

Suitable when you already have a UK IP address.

docker run -d \
  --name iplayer-arr \
  -e TZ=Europe/London \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=002 \
  -p 8191:8191 \
  -v /path/to/config:/config \
  -v /path/to/downloads:/downloads \
  ghcr.io/will-luck/iplayer-arr:latest

With VPN (PIA Example)

The base image (ghcr.io/hotio/base:alpinevpn) includes built-in WireGuard VPN support via s6-overlay. VPN is disabled by default.

docker run -d \
  --name iplayer-arr \
  --cap-add NET_ADMIN \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -e TZ=Europe/London \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=002 \
  -e VPN_ENABLED=true \
  -e VPN_PROVIDER=pia \
  -e VPN_PIA_USER=p1234567 \
  -e VPN_PIA_PASS=YourPassword \
  -e VPN_PIA_PREFERRED_REGION=uk \
  -e VPN_LAN_NETWORK=192.168.1.0/24 \
  -e WEBUI_PORTS=8191/tcp \
  -p 8191:8191 \
  -v /path/to/config:/config \
  -v /path/to/downloads:/downloads \
  ghcr.io/will-luck/iplayer-arr:latest

--cap-add NET_ADMIN and the sysctl flag are required for the VPN tunnel to function. VPN_LAN_NETWORK should match your local subnet so the web UI remains accessible. WEBUI_PORTS tells the container which port to keep routable outside the tunnel.

See VPN Configuration for the full list of VPN variables and supported providers.

---

Docker Compose

Basic (No VPN)

services:
  iplayer-arr:
    image: ghcr.io/will-luck/iplayer-arr:latest
    container_name: iplayer-arr
    environment:
      - TZ=Europe/London
      - PUID=1000
      - PGID=1000
      - UMASK=002
    ports:
      - 8191:8191
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

With VPN (PIA Example)

services:
  iplayer-arr:
    image: ghcr.io/will-luck/iplayer-arr:latest
    container_name: iplayer-arr
    cap_add:
      - NET_ADMIN
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    environment:
      - TZ=Europe/London
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - VPN_ENABLED=true
      - VPN_PROVIDER=pia
      - VPN_PIA_USER=p1234567
      - VPN_PIA_PASS=YourPassword
      - VPN_PIA_PREFERRED_REGION=uk
      - VPN_LAN_NETWORK=192.168.1.0/24
      - WEBUI_PORTS=8191/tcp
    ports:
      - 8191:8191
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

---

First Run

Once the container is running, open http://localhost:8191 in your browser. The setup wizard appears automatically on first launch and guides you through initial configuration.

If you are using a VPN, verify your tunnel is active before proceeding -- downloads will fail without a UK IP address.