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.
-
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.debThe same files are on the Download page, with their sizes: amd64 is for Intel and AMD processors and arm64 for ARM. If
wgetis missing,sudo apt install wgetadds 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
watchmymediauser, 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.
- It makes a
-
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 ashttp://192.168.1.20:27587.hostname -Iprints 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.
-
Let the server read your folders
The server runs as its own
watchmymediauser, not as you, so it reads only what that user may read. A folder everyone can read, as folders under/srvor/mntoften 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/MoviesThe folders above it have to let that user through as well. For a home folder:
sudo setfacl -m u:watchmymedia:x /home/alexThat 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.
-
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 WatchMyMediaThat 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=mdnsandsudo 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 installsmesa-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 usei965-va-driver. - Intel Quick Sync: add
libvpl2andlibmfx-gen1.2to 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 watchmymediasays whether it is running, andsudo systemctl restart watchmymediarestarts it, which stops anything playing or recording. -
Logs go to the system's journal:
sudo journalctl -u watchmymedia. Add-fto watch new lines arrive, or-bfor 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 withsudoedit /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.