nvidia-vaapi-driver: NVDEC behind VA-API, built for Firefox and hobbled by the EGL regression

A VA-API shim over NVDEC, scoped to one application

The scope statement is in the first paragraph and it is unusually honest. This is a VA-API implementation that uses NVDEC as a backend, specifically designed to be used by Firefox for accelerated decode of web content, and it may not operate correctly in other applications.

That sentence should govern your expectation. The value proposition is narrow and real: Linux applications that already call VA-API, including Firefox, get hardware decode from an NVIDIA card without every application needing NVDEC-specific code. The cost is that the driver makes no general compatibility promise, and there is an implication worth stating plainly: if Firefox works, that does not mean your video editor will.

The source is C, the default branch is master, and the last push was on 2026-10-11. Releases are v0.0.18 on 2026-08-31, v0.0.17 on 2026-05-09 and v0.0.16 on 2026-02-24. The version numbers have not reached 1.0, and the README points at issue 116 for the encoding support question.

The codec table says no to MPEG-4 and JPEG for structural reasons

Hardware decoding only, since encoding is not supported. Within that, the table is mostly favorable: AV1 requires Firefox 98 or newer, H.264, VP8, MPEG-2 and VC-1 carry no extra conditions, VP9 requires being compiled with `gstreamer-codecparsers-1.0`, and HEVC carries the caveat that some distros ship Firefox and FFMPEG with HEVC support disabled due to patent concerns, which is a distribution decision rather than a driver one.

The two unsupported entries explain themselves in a way that tells you the limits are architectural. MPEG-4 fails because VA-API does not supply enough of the original bitstream to allow NVDEC to decode it. JPEG is marked as unlikely to ever work because the two APIs are too different. Neither is a bug waiting to be fixed in a later release.

One capability sits outside the table. YUV444 is supported but requires a Turing-generation card (20XX or 16XX), HEVC, and the direct backend. So three conditions must hold simultaneously, which makes it the feature most likely to fail quietly on an older card.

To check what your own card can decode, the README points at the `vainfo` command with this driver installed, or at NVIDIA's own decode support matrix.

Installing with the script, and what it does to your system

Requirements are an NVIDIA driver series 470 or 500+, and the kernel side must have the nvidia_drm module configured with `nvidia-drm.modeset=1`.

The installer path is three commands:

git clone https://github.com/elFarto/nvidia-vaapi-driver.git
cd nvidia-vaapi-driver
./install.sh --deps --clean

What the installer does is worth reading before you run it. It builds the driver, backs up any existing `nvidia_drv_video.so`, installs the new driver into libva's driver directory, and runs a `vainfo` smoke test when possible. To skip dependency installation:

./install.sh --clean

And it prints a rollback command if it replaced an existing driver. That last detail is the one to note: the installer overwrites a file that libva loads, so keeping the printed rollback string before you lose the ability to restore your previous driver.

Packaging exists outside the script. openSUSE ships it as `nvidia-vaapi-driver` and also as `libva-nvidia-driver`, and the README points at repology and pkgs.org for other distributions, inviting a distribution to submit a package if it is not listed. If your distribution packages it, you are better off using that package than the script.

Building by hand needs meson and two header sets

If you are packaging rather than installing, the manual route is meson, the `gstreamer-plugins-bad` library, and nv-codec-headers from the VideoLAN git. The dependency table gives package names per manager.

For pacman: `meson gst-plugins-bad ffnvcodec-headers`. For apt: `meson gstreamer1.0-plugins-bad libffmpeg-nvenc-dev libva-dev libegl-dev libdrm-dev`, with `libgstreamer-plugins-bad1.0-dev` listed as optional for additional codec support. For yum/dnf: `meson libva-devel gstreamer1-plugins-bad-freeworld nv-codec-headers libdrm-devel`, with `gstreamer1-plugins-bad-free-devel` as the optional extra.

Those optional packages are not decorative. VP9 support requires compiling with `gstreamer-codecparsers-1.0`, so on apt or dnf the codec you want may be missing until you install the optional development package.

The build itself is two commands:

meson setup build
meson install -C build

The repository ships extract_headers.sh and headers.in at the top level, next to nvidia-include/, which is the mechanism for generating the NVIDIA headers the source needs against your installed driver.

The EGL backend is broken from driver 525, so the default is direct

This is the operational fact to carry into any deployment. The EGL backend is broken on driver versions 525 or later due to a regression, and users on those drivers should use the direct backend instead. The README links NVIDIA's forum bug report and issue #126.

The backend is selected by environment variable rather than build flag:

| Variable | Purpose | |---|---| | `NVD_BACKEND` | Either `egl` or `direct`, with `direct` as the default. | | `NVD_LOG` | `1` logs to stdout, anything else appends to the given file. | | `NVD_MAX_INSTANCES` | Maximum concurrent driver instances per process, described as only really useful for older GPUs with not much VRAM, especially with Firefox on video heavy websites. | | `NVD_MAX_DETACHED_BACKING_IMAGES` | Target upper bound on the number of cached detached backing images, default `16`, and `0` reclaims every eligible detached image. | | `NVD_MAX_DETACHED_BACKING_IMAGE_BYTES` | Target upper bound in bytes on the direct backend's detached backing-image cache, which recycles decode surfaces across stream switches. |

The byte cap is worth understanding rather than just copying. Its default scales with the GPU as total VRAM divided by 64 (roughly 1.6 percent), clamped to between 64 MiB and 512 MiB, falling back to `134217728` (128 MiB) when the VRAM size cannot be queried. Lowering it reduces memory usage on a low-VRAM GPU at the cost of more reallocation when streams change. Setting it to `0` reclaims everything eligible.

On Linux, a detached image with DMA-BUF references held by the client is not eligible for reclamation, so it may temporarily exceed either cache target until the client closes those references. If you are debugging memory growth, that is the mechanism to look at.

Removal has a symlink to restore

The driver installs itself as `/usr/lib64/dri/nvidia_drv_video.so`, or `/usr/lib/x86_64-linux-gnu/dri/nvidia_drv_video.so` on some distributions. Uninstalling is removing that file.

There is a catch the README spells out. That file is usually symlinked to `/usr/lib64/dri/vdpau_drv_video.so`, or the corresponding multiarch path, if the VDPAU to VA-API driver is installed. So the symlink has to be restored for that other driver to work normally again. A removal that leaves a dangling symlink into libva's driver directory can break VDPAU-backed playback for reasons that have nothing to do with NVIDIA, which makes this the kind of uninstall worth doing carefully.

Where this driver is the wrong choice

The boundaries are structural and the README states most of them.

Encoding is out, since NVDEC is a decoder and the driver exposes only decode paths. JPEG and MPEG-4 are out for the reasons above. Anything needing general application support beyond Firefox is out by the project's own statement. And YUV444 needs Turing or later, HEVC, and the direct backend at once.

There is also a dependency risk that comes with the design. This is a third-party shim whose documented compatibility is primarily focused on Firefox. On a driver update, or an application that starts using a VA-API entry point the shim does not handle, your fallback is the CPU decoder rather than a configuration change. The last push was on 2026-10-11 and v0.0.18 landed on 2026-08-31, so the project is active, but its version numbers below 1.0 signal the same thing: this is still work in progress being maintained rather than a settled interface.

If your use is Firefox video playback on an NVIDIA card on Linux, this is a good answer. If your use is a workstation application that happens to decode video among other things, test it against that application specifically, because the README tells you not to assume it will work.

Editorial conclusion

nvidia-vaapi-driver fits an NVIDIA Linux user whose applications speak VA-API rather than NVDEC directly, and whose hardware decode requirements are covered by the codec table. It does not fit anyone needing hardware encoding, MPEG-4 or JPEG decode, or general-purpose applicability beyond Firefox. Before installing, check your codec needs against the table, confirm your NVIDIA driver series is 470 or 500+, make sure the nvidia_drm module is configured with nvidia-drm.modeset=1, and keep the rollback command the installer prints, because the file it replaces is a shared libva driver path.

Frequently asked questions

Official sources

1. elFarto/nvidia-vaapi-driver on GitHub
2. Issues
3. README
4. Releases