jellyfin-qnap: packaging the Jellyfin server as a QNAP QPKG

An automatic packaging pipeline, not a curated build

The README is upfront about what this repository is and is not. It is Jellyfin server packaging for QNAP NAS, and the compatibility section states that releases are created automatically from the latest Jellyfin releases and are not field-tested nor official ones from Jellyfin or QNAP. The last release with the maintainer's endorsement is the one deployed on their own QNAP and working properly, which is a reasonable proxy but not a test matrix. The package.json shows how the versioning works: the package version 122.0.813 pairs with a server version of 12.2 and a qpkg_ver of 12.2.0, and the release tags follow the same scheme, so 121.3.812_718176d7 maps to Jellyfin 12.1.3 and 121.2.812.2_ec96c2f0 to 12.1.2. The bundled ffmpeg is pinned at 8.1.3 in the same file, and there is a separate opencl field recording 2.41.5 alongside an opencl_legacy value.

Installing is a signed-app toggle and one file

The installation path is a QNAP QPKG install, and there is one setting you have to change first. You download the .qpkg from the Releases page. On the Qnap QTS you go to App Center, then Settings, then Allow installation of applications without a valid digital signature. Then on the Qnap QTS you go to App Center, then Install Manually, and choose the downloaded .qpkg. After installation, on the Jellyfin entry appearing in the App Center you wait a bit, around thirty seconds, and then open it with the Open button, and it opens a working web site. The README notes that if it does not open or raises a connection refused, try the default http default port 8096. On first open you choose a server, which is the IP of your NAS, and create a user.

VAAPI acceleration on a QNAP, with the caveats spelled out

The hardware acceleration section is the part of the README that will save the most time, because it names the exact settings and then admits they might not work. You go to Admin, then Dashboard, then Server, then Playback, and set Transcoding, then Hardware acceleration to Video Acceleration API (VAAPI), and Transcoding, then VA API Device to /dev/dri/renderD128. The README then says this shall be OK, but maybe not. The troubleshooting section says you can find a log of vainfo of your NAS under Advanced, then Logs, then vainfo-*.log, which helps you find which driver or options to enable. A dedicated plugin is now installed by default on the Jellyfin server, at Plugins, then QNAP.Configuration, where you can change the default vaapi driver used while loading a video, from defaultValue to iHD or i965. And there is one model-specific warning: on a TS-253A, the option Enable 10-Bit hardware decoding for HEVC shall be disabled.

OpenCL tonemapping needs a second package and a restart

If you want and can use OpenCL for tonemapping, you can install the corresponding package jellyfin-opencl aside the jellyfin one, and the README notes that OpenCL shall be already installed when Jellyfin is started, so you may need to restart Jellyfin for the package to take effect. The order matters in two ways. You can install or update jellyfin-opencl and then install or update jellyfin, or you can install jellyfin, then install jellyfin-opencl, and restart jellyfin from the App Center. After that you configure Jellyfin to use OpenCL. The reason this needs its own package rather than a flag is that the OpenCL runtime has to be present in the container image before the server starts, and the package.json records the two OpenCL versions the build ships, a current one at 2.41.5 and a legacy one at 1.0.17537.24.

HTTPS with a child certificate from the NAS certificate

The networking section covers changing the HTTP port and enabling HTTPS, and then walks through generating a certificate. To change the port you go to Administration, then Dashboard, then Advanced, then Networking, change the Server Address Settings, then Local HTTP port number, and then do Stop and Start on Jellyfin in the QNAP App Center. For HTTPS you enable it in the same place and change the Local HTTPS port number, put the path to your p12 certificate if you have one, and restart from the App Center. You can use the certificate of your NAS directly, downloading it and generating a p12 from it, or create a new child certificate. The private key is generated with openssl genrsa -out newkey.key 2048, and a configuration file openssl-cert.conf is written with a distinguished name and subjectAltName entries for the NAS IP and hostname:

[req]
distinguished_name = req_distinguished_name
req_extensions = req_ext
prompt = no

[req_distinguished_name]
C   = FR
ST  = Paris
L   = Paris
O   = pdulvp
CN  = Jellyfin QNAP

[req_ext]
subjectAltName = @alt_names

[alt_names]
IP.1 = 192.168.1.xxx
DNS.1 = nasfxxxxxx

The certificate request, the signing and the p12 packaging commands follow it. On the client you then install the certificate as trusted, either the Jellyfin one or the QNAP one as a trusted root.

user-config.sh is how you keep your changes across updates

The customization note is short and important for anyone who plans to modify the package. You can customize the startup of Jellyfin by creating a new file user-config.sh in the installation folder, rather than editing provided scripts, and it will not be erased after updates. The README points at the user-config.sh.sample provided alongside. That is a deliberate design decision in a project whose releases are replaced wholesale on every upstream Jellyfin version: if you had to edit the shipped scripts, every automated update would overwrite your edits, and the alternative to that, forking the package, is heavy. A file the update leaves alone is the middle path. The repository tree shows the rest of the build machinery, with a Dockerfile-qbuild for the QNAP build container, a Dockerfile-qpkg-tester, packaging/ and packaging-opencl/ directories, plugins/ for the QNAP.Configuration plugin, and scripts including make-on-docker.sh, push.sh and version-check.sh.

What this packaging cannot promise

Three limits are worth stating before you rely on it. First, the automatic builds are not field-tested, so a release may work on one QNAP model and not another, and the compatibility list is a GitHub issue where the maintainer asks people to comment with their model and result, which means the coverage grows as people report rather than being tested up front. Second, the package is tied to the QPKG format, so it is for QNAP hardware and QTS only; a NAS user on another platform gets nothing from it, and the QNAP hardware acceleration story depends on the VAAPI device path being present, which is not guaranteed across all models. Third, the documentation is written in a conversational register with several hedges, so a setting that the README says shall be OK, but maybe not needs testing on your own hardware before you rely on it. The project is MIT licensed according to the package.json, though the repository metadata does not classify the licence, and the last push was on 2026-10-06.

Editorial conclusion

Adopt jellyfin-qnap if you run Jellyfin on a QNAP NAS and want it installed and updated through the App Center rather than from a container or by hand. Do not adopt it expecting an official or field-tested build, because the README states that the releases are created automatically from the latest Jellyfin releases and are not field-tested nor official ones from Jellyfin or QNAP. Before you commit, read the compatibility list issue and comment on your model, check that the bundled ffmpeg version matches what your library needs, and set up the user-config.sh file before your first update so your customisations survive.

Frequently asked questions

Official sources

1. Issues
2. pdulvp/jellyfin-qnap on GitHub
3. Project website
4. README
5. Releases