Install WatchMyMedia on Debian or Ubuntu

One package runs the server as a system service. It starts with the computer, and new versions come with the system's other updates. Everything here is typed in a terminal.

You'll need

  • Debian 13 or 12, or Ubuntu 26.04 or 24.04, on an Intel or AMD (amd64) or ARM (arm64) processor. Other releases, and systems built on these, aren't tested.
  • An account that can use sudo.
  • Your movies and TV shows in folders on that computer, or on a drive or share it mounts, with movies and TV shows in separate folders.

On Fedora, install the Fedora package. On another distribution or a NAS, run it with Docker. On Unraid, install it from Community Applications.

  1. Download and install the package

    These two lines fetch the newest package for this computer's processor and install it:

    wget -O watchmymedia.deb "https://downloads.watchmy.media/apt/latest?arch=$(dpkg --print-architecture)"
    sudo apt install ./watchmymedia.deb

    The same files are on the Download page, with their sizes: amd64 is for Intel and AMD processors and arm64 for ARM. If wget is missing, sudo apt install wget adds it.

    The package holds the server and the FFmpeg it converts video with. apt adds a few packages beside it: the libraries a GPU needs, and acl, for a command in step 3. The install then does three things:

    • It makes a watchmymedia user, and a service of the same name that runs the server as that user, now and each time the computer starts.
    • It adds WatchMyMedia's repository to apt, so new versions come with the system's updates.
    • It prints the address to open.

    To have apt fetch the package from that repository instead of a file, add the repository first.

  2. Open it in a browser

    On the computer itself, open http://localhost:27587. From another computer or a phone on the same home network, use the address the install printed, such as http://192.168.1.20:27587. hostname -I prints the computer's addresses again.

    Setup opens: create your account, which becomes the admin, and add a free TMDB key for posters. Set up your server goes through every step. If another device can't open the address, a firewall may be in the way: that is step 4.

  3. Let the server read your folders

    The server runs as its own watchmymedia user, not as you, so it reads only what that user may read. A folder everyone can read, as folders under /srv or /mnt often are, works as it is. A folder inside your home folder doesn't: Debian and Ubuntu close home folders to other users.

    When you add a folder the server can't read, setup and Settings › Libraries say so and give the command that lets it in. For a folder called Movies in the home folder of a user called alex, it is:

    sudo setfacl -R -m u:watchmymedia:rX /home/alex/Movies

    The folders above it have to let that user through as well. For a home folder:

    sudo setfacl -m u:watchmymedia:x /home/alex

    That lets the server pass through your home folder to Movies. It still can't list or read anything else there, or change anything in Movies. Then check the folder again in the browser. Drives, shares and recordings, further down, has the other cases.

  4. Open the firewall, if you use one

    The package never changes a firewall. Debian installs none. If you have turned on Ubuntu's firewall, ufw, let the server through it:

    sudo ufw allow WatchMyMedia

    That opens TCP port 27587, the only port browsers and the apps connect to. With firewalld, the lines are sudo firewall-cmd --permanent --add-service=watchmymedia --add-service=mdns and sudo firewall-cmd --reload. The apps look for the server by name on your network; where a firewall stops that, type the server's address into the app.

You're done when systemctl status watchmymedia says active (running) and the browser opens your library.

Add the repository first

Installing the file is enough, because the package adds the repository itself. The other way round also works: add the repository and its key, then let apt fetch the package, which it checks against the repository's signed list.

sudo wget -O /usr/share/keyrings/watchmymedia-archive-keyring.gpg https://downloads.watchmy.media/apt/watchmymedia-archive-keyring.gpg
sudo wget -O /etc/apt/sources.list.d/watchmymedia.sources https://downloads.watchmy.media/apt/watchmymedia.sources
sudo apt update
sudo apt install watchmymedia

Check the key

The key belongs to Eldwick Software, which makes WatchMyMedia. To check the one you have, gpg --show-keys /usr/share/keyrings/watchmymedia-archive-keyring.gpg prints its fingerprint (sudo apt install gnupg adds gpg where it is missing). It should be:

3C3CE93DA59EBE83C4B3ED24CB959CFB56BCDBB9

apt doesn't check a .deb file you downloaded yourself against that key. For such a file, compare what sha256sum watchmymedia.deb prints with the SHA-256 beside the file under Release notes and earlier versions on the Download page.

Stop using the repository

Add a line Enabled: no to /etc/apt/sources.list.d/watchmymedia.sources. Updates to WatchMyMedia keep that change, and you then update by installing a newer file.

Drives, shares and recordings

Files you add later

The first command in step 3 covers what is in the folder now. Files added later usually open to everyone and need nothing more. If yours don't, give the folder a default as well, which every new file and folder inside it takes:

sudo setfacl -R -d -m u:watchmymedia:rX /home/alex/Movies

Where the server writes

Reading is enough to play a library. The server writes only where it records live TV, where you delete a title from the web app, and where it saves a subtitle or a trailer beside a video. For those folders, use rwX in place of rX, with the default too:

sudo setfacl -R -m u:watchmymedia:rwX /srv/media/Recordings
sudo setfacl -R -d -m u:watchmymedia:rwX /srv/media/Recordings

A folder several accounts share

For a media folder outside anyone's home folder, a group does the same job. This makes one called media, for the server and for alex:

sudo groupadd media
sudo usermod -aG media watchmymedia
sudo usermod -aG media alex
sudo chgrp -R media /srv/media
sudo chmod -R g+rwX /srv/media
sudo find /srv/media -type d -exec chmod g+s {} +
sudo systemctl restart watchmymedia

The find line makes new files take the folder's group. The restart puts the server in its new group; alex signs out and in again for theirs.

A drive

A drive the desktop mounts when you plug it in, under /media and your user name, is yours alone. The server can't read it, and it isn't there until you sign in. For a library, mount the drive when the computer starts, with a line in /etc/fstab. lsblk -f shows each drive's UUID and file system. For a drive with a Linux file system, such as ext4:

UUID=…  /mnt/media  ext4  defaults,nofail  0  2

Then give its folders to the server as above. A drive formatted exFAT or NTFS keeps no Linux permissions, so the line sets them for the whole drive. This one lets everyone read it:

UUID=…  /mnt/media  exfat  defaults,nofail,umask=022  0  0

Add uid= and the number id -u watchmymedia prints if the server should write there too. An NTFS drive takes the same options, with the type your system uses for NTFS (ntfs3, or ntfs-3g from the package of that name). Make the folder first (sudo mkdir /mnt/media), and after changing the file run sudo systemctl daemon-reload and sudo mount -a.

A share on a NAS or another computer

Mount it when the computer starts too, not from the file manager. For a Windows (SMB) share, install cifs-utils and add a line like this, where the credentials file holds a username= line and a password= line and only root can read it:

//nas.local/Movies  /mnt/movies  cifs  credentials=/etc/nas-credentials,uid=watchmymedia,gid=watchmymedia,nofail,_netdev  0  0

For an NFS share, install nfs-common. The NAS decides who may read an NFS share, so export it readable by everyone, or by the user number id -u watchmymedia prints:

nas.local:/volume1/Movies  /mnt/movies  nfs  defaults,nofail,_netdev  0  0

Convert video on the GPU

Without a GPU the server converts video on the processor, which works but is slower. With one, the package's FFmpeg reaches it through the system's own driver, so the driver is what you install. The watchmymedia user is already in the render and video groups, which own the GPU, so there is no group to add.

  • AMD: sudo apt install mesa-va-drivers. On Ubuntu 26.04 that name installs mesa-libgallium, which holds the driver.
  • Intel: sudo apt install intel-media-va-driver. Going by its description and Intel's own notes, that build encodes H.264 on Skylake and newer GPUs and HEVC on Ice Lake and newer. intel-media-va-driver-non-free, from Debian's non-free component or Ubuntu's multiverse, adds HEVC on Skylake to Comet Lake and H.264 on Broadwell. Older Intel GPUs use i965-va-driver.
  • Intel Quick Sync: add libvpl2 and libmfx-gen1.2 to the Intel driver.
  • NVIDIA: install NVIDIA's driver the way Debian or Ubuntu describes for your release. This page names no package for it, because none has been checked.

On Debian 13 and 12 and on Ubuntu 24.04, installing WatchMyMedia usually brings the AMD driver with it, and on Intel and AMD processors the Intel one. On Ubuntu 26.04 it brings no driver, so install yours from the list. Debian 12 and Ubuntu 24.04 carry older drivers, which don't know the newest GPUs: a new GPU may need Debian 13 or Ubuntu 26.04.

Then open Settings › Transcoding in the web app. Its Encoder section names the encoder in use and whether it passed its test. If the server fell back to software, a banner says so, with Test again and Choose another.

What has been checked: the package names, read from each release's own package lists. Nobody has yet converted a video on an Intel, AMD or NVIDIA GPU with this package, so this page can't promise that yours will be used. If you'd rather use Jellyfin's FFmpeg, which carries its own Intel and AMD drivers, install jellyfin-ffmpeg8 from Jellyfin's repository and set ffmpeg.ffmpeg and ffmpeg.ffprobe in the settings file to its two programs. That hasn't been tried either.

Update it

New versions come from WatchMyMedia's repository, with the system's other updates. To update only WatchMyMedia now:

sudo apt update && sudo apt install --only-upgrade watchmymedia

Check for updates, under Settings › General, says when a newer version is out and gives the same line. An update restarts the server, which stops anything playing or recording, so pick a quiet moment.

Back up first: 2.0.0 changes the server's database, and going back to 1.8.0 afterwards needs a backup made before the update. sudo -u watchmymedia watchmymedia backup makes one. If the system updated it before you could, Updates and backups says which backup to use.

The service, its files and its logs

  • The service is called watchmymedia. systemctl status watchmymedia says whether it is running, and sudo systemctl restart watchmymedia restarts it, which stops anything playing or recording.
  • Logs go to the system's journal: sudo journalctl -u watchmymedia. Add -f to watch new lines arrive, or -b for the lines since the computer started.
  • Your library's data, which is its database, artwork and backups, is in /var/lib/watchmymedia. Video being converted is in /var/cache/watchmymedia. Both are closed to the computer's other users.
  • The settings file is /etc/watchmymedia/config.yaml. Every option in it starts commented out, because nearly everything is set in the web app. Edit it with sudoedit /etc/watchmymedia/config.yaml, then restart the service. Its first lines say how to move the two folders above.
  • The server's own commands run as its user, so that they use the same folders. A backup, for example: sudo -u watchmymedia watchmymedia backup.

Remove it

sudo apt remove watchmymedia

This stops the service and removes the program. It keeps your library's data in /var/lib/watchmymedia and your settings file, so installing the package again carries on where you left off. Your video files are never touched.

sudo apt purge watchmymedia

This also removes the settings file and the video being converted. It still leaves /var/lib/watchmymedia, and says so. To delete that too, which can't be undone, run sudo rm -r /var/lib/watchmymedia. Neither command removes the watchmymedia user.

If it doesn't work

Written on November 18, 2026, for WatchMyMedia 1.7.0, the first release with this package; not yet followed step by step on a real Debian or Ubuntu system. The package was installed, updated and removed in containers of Debian 13 and 12 and Ubuntu 26.04 and 24.04, and the folder commands in step 3 and after it were run in a Debian 13 container. Step 1 and Add the repository first were run in Debian 13 containers against this site's repository, where both installed 1.7.0 and the repository updated. The firewall, drive and share lines and everything about GPUs have not been tried. Update it gained the 2.0.0 backup note on November 21, 2026.