Leaving Fetch TV?Read the guideRead the guideSkip to content

Windows (untested) ​

WARNING

Everything on this page is untested and theoretical. The author has no Windows PC and has never run Freetvarr on Windows. The steps come from the Microsoft and Docker documentation and from forum reports, not from a working install. Expect to troubleshoot, and expect some parts not to work. The supported route is a NAS or a mini PC that runs Linux (see The computer).

Freetvarr and TVHeadend (the program that runs the tuner and records) are Linux programs in Docker containers. Windows runs Linux containers inside WSL (Windows Subsystem for Linux), which is a small Linux virtual machine. That virtual machine is the source of most of the limits below: by default it has its own network address, and it has no access to a USB tuner or to the graphics chip in the way that Freetvarr uses them.

The most likely route is Docker Engine inside an Ubuntu distribution in WSL, with WSL's mirrored networking turned on (Ubuntu then shares the PC's own network address). Docker Desktop is simpler to install but has more network limits.

The Windows PC ​

PartMinimumRecommendedWhat it changes
WindowsWindows 11 version 22H2, 64-bitThe latest Windows 11Mirrored networking needs Windows 11 22H2 or later. Without it, the tuner and your phones cannot reach the containers easily
ProcessorA 64-bit Intel or AMD processor with 4 cores, with virtualisation turned on6 cores or moreLive TV in the browser converts in software only (see Live TV conversion)
Memory (RAM)8GB16GBWSL takes up to half of the memory by default, and Windows needs the rest
StorageAn SSD for Windows and WSL, with room for the recordings: 3–6GB per hour of HDA second large drive for recordings (see Storage)WSL keeps its files in one virtual disk, 1TB at most by default
NetworkWired network on the same part of the network as the tunerThe sameWi-Fi adds dropouts to live TV and recordings
PowerA PC that never sleepsA small, quiet desktop or mini PCA PC that sleeps, shuts down, or restarts for an update misses the recordings due in that time

Virtualisation is a setting in the PC's BIOS or UEFI firmware, often called Intel VT-x, AMD-V, or SVM. WSL and Docker do not start without it.

Windows 10 has no mirrored networking. On Windows 10 only the Docker Desktop route applies, with all of its network limits.

Setup steps ​

These steps install Docker Engine inside Ubuntu in WSL. Each step links to the source it comes from.

  1. In the PC's BIOS or UEFI firmware, turn on virtualisation (see The Windows PC).

  2. In PowerShell (as administrator), run:

    powershell
    wsl --install

    This installs WSL and Ubuntu (Microsoft: Install WSL). Restart the PC when it asks, then open Ubuntu from the Start menu and create a Linux username and password.

  3. In File Explorer, create the file .wslconfig in your user folder (C:\Users\<your name>), with this content (Microsoft: WSL settings):

    ini
    [wsl2]
    networkingMode=mirrored
    
    [general]
    instanceIdleTimeout=-1

    networkingMode=mirrored gives Ubuntu the PC's own network address. instanceIdleTimeout=-1 stops WSL from shutting Ubuntu down when no window is open.

  4. In PowerShell (as administrator), allow devices on your network to connect into WSL (Microsoft: WSL networking):

    powershell
    Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
  5. In PowerShell, run:

    powershell
    wsl --shutdown

    Wait 10 seconds, then open Ubuntu again so the new settings apply.

  6. In Ubuntu, check that /etc/wsl.conf has these lines, and add them if not. Docker Engine needs systemd to start by itself.

    ini
    [boot]
    systemd=true

    To edit the file, run:

    sh
    sudo nano /etc/wsl.conf
  7. In Ubuntu, install Docker Engine and the Docker Compose plugin from Docker's own instructions (Docker: Install Docker Engine on Ubuntu). Then add your user to the docker group (Docker: Linux post-install steps).

  8. In Ubuntu, move to your home folder:

    sh
    cd ~

    Then run the install command from Getting started. Keep the freetvarr folder in your Ubuntu home folder, not under /mnt/c (see Storage).

  9. On a phone or another computer, open http://<windows-pc-ip>:3733 and run setup. To find the PC's address, run this in PowerShell and read the IPv4 address of the wired adapter:

    powershell
    ipconfig
  10. In the Channels step of setup, if setup finds no tuner, press Enter the tuner's address. Enter the tuner's IP address and the Windows PC's IP address, then press Use this address.

The install script stops in Git Bash and other Windows terminals. Run it only in the Ubuntu terminal.

Limits ​

Tuner discovery ​

TVHeadend finds an HDHomeRun by a network broadcast, so the TVHeadend container needs network_mode: host on the same network as the tuner. Microsoft lists multicast support and direct access from the network as features of mirrored networking (Microsoft: WSL networking). Nobody has confirmed that an HDHomeRun broadcast reaches TVHeadend this way. If it does not, enter the tuner's address by hand, as in step 10. The tuner then sends each stream to the PC on UDP port 9983, which the Windows firewall must also let through.

Phones and TVs ​

With mirrored networking and the firewall setting in step 4, a phone or TV on your network opens Freetvarr at the Windows PC's address. Without mirrored networking, WSL has its own private address, and each port needs a Windows port forward (netsh interface portproxy) to that address. That address changes when WSL restarts (Microsoft: WSL networking). Freetvarr uses port 3733, and Plex (if you add it) uses 32400.

Live TV conversion ​

Freetvarr's hardware conversion uses VAAPI (the Linux interface to the graphics chip's video encoder) on /dev/dri, the Linux graphics device. WSL shares the graphics chip in another way (through a Direct3D 12 driver), and Freetvarr does not set that up (Microsoft: GPU video acceleration in WSL). Plan for software conversion only, with the limits in The computer: live TV in the browser at 540 lines, and only as many live streams as the processor converts smoothly. Do not use the hardware override file from Hardware transcoding. Recording needs no conversion, so recordings are not affected.

USB tuners ​

A USB tuner does not work. The usbipd-win tool connects a USB device to WSL, but the WSL kernel has no DVB drivers (the Linux drivers for TV tuners), so TVHeadend has no tuner to use. A custom WSL kernel is the only way around it (usbipd-win: WSL support), and a TVHeadend forum user reports that a DVB tuner still did not work in WSL with it (TVHeadend forum). Use a network tuner.

Storage ​

Keep the freetvarr folder, and so the recordings, in the Ubuntu file system. Microsoft recommends the Linux file system for Linux programs, because files under /mnt/c are slower to reach (Microsoft: Working across file systems). Windows drives also do not keep the Linux file owners that PUID and PGID (the user and group in Freetvarr's .env) set. The Ubuntu file system is one virtual disk file on the C: drive, 1TB at most by default (defaultVhdSize in .wslconfig).

To copy a recording to Windows, open \\wsl$\Ubuntu\home\<linux username>\freetvarr\data in File Explorer. To back up Freetvarr's settings, stop Freetvarr and copy the whole freetvarr\config folder out the same way (see Backups).

Always on ​

TVHeadend records only while the PC is on and Ubuntu is running:

  • In Windows Settings → SYSTEM → Power, set sleep to Never.
  • Windows Update restarts the PC. Set Active hours in Settings → Windows Update → Advanced options to cover the times you record most.
  • After a restart, WSL does not start until something starts it. A Task Scheduler task that runs wsl.exe -d Ubuntu when you sign in starts Ubuntu, and Docker Engine then starts the containers. Forum reports say a task that runs before sign-in is unreliable, so sign-in after each restart may be necessary.

A desktop PC that stays on uses more power than a NAS or a mini PC.

Docker Desktop ​

Docker Desktop is a Windows app that runs Docker in WSL for you. It is free for personal use and for small businesses (Docker: Docker Desktop licence). It needs 8GB of memory, and Docker lists Windows 10 22H2 and Windows 11 23H2 or later (Docker: Install Docker Desktop on Windows). In Settings → General, turn on Start Docker Desktop when you sign in to your computer.

Its network limits are larger:

  • Host networking (Docker Desktop 4.34 or later) does not give the containers the PC's network addresses (Docker: Host network driver), so TVHeadend cannot find the tuner by broadcast. Enter the tuner's address by hand.
  • Docker Desktop does not use WSL's mirrored networking (Docker forum).
  • Whether the tuner's streams on port 9983 reach TVHeadend, and whether phones reach port 3733, is untested.

Run the install command in the Ubuntu terminal, with Docker Desktop's WSL integration turned on for Ubuntu, not in PowerShell.

The supported route ​

A small NAS or a mini PC that runs Linux avoids every limit on this page: the tuner is found by itself, Quick Sync (the video encoder in Intel processors) converts live TV, and the computer stays on with little power. See The computer for specs and examples, and Getting started for the install.

GPL-3.0-or-later. Not affiliated with or endorsed by SiliconDust, TVHeadend, or Plex.