Cómo usar una GPU NVIDIA para transcodificar en Jellyfin

Qué va a configurar

La transcodificación por hardware de Jellyfin en una GPU NVIDIA consta de cuatro pasos en un orden fijo. Sólo el último se realiza dentro de Jellyfin. El contenedor no puede ver una GPU cuyo controlador no haya cargado el host. Jellyfin no puede usar una GPU que el contenedor no pueda ver. Siga este orden y cada fallo tendrá un lugar claro donde buscar.

1. Instale el controlador de NVIDIA en el host y confírmelo con nvidia-smi.
2. Instale NVIDIA Container Toolkit para que Docker pueda asignar una GPU a un contenedor.
3. Reserve la GPU para el servicio de Jellyfin en docker-compose.yml y confirme que el contenedor puede verla.
4. Active NVENC y NVDEC en los ajustes de reproducción de Jellyfin y confirme que una reproducción real los utiliza.

NVENC (codificador de NVIDIA) y NVDEC (decodificador de NVIDIA) son bloques de función fija de la tarjeta. Son componentes de silicio independientes de los núcleos de sombreado que ejecutan tareas de CUDA (compute unified device architecture). Esa separación es la razón principal para usar esta configuración: una transmisión que consume varios núcleos de CPU mediante software utiliza una pequeña fracción de un núcleo y un bloque de hardware dedicado de la GPU.

La reproducción directa es mejor que cualquier transcodificación, así que compruébelo primero

Antes de configurar nada de esto, determine si está transcodificando por un motivo que pueda eliminar fácilmente. Jellyfin transcodifica cuando el cliente no puede reproducir el archivo tal como está. El motivo siempre pertenece a una lista breve: el códec de vídeo, el códec de audio, el formato del contenedor, los subtítulos basados en imágenes o un límite de bitrate solicitado por el cliente.

Abra Dashboard y, después, Playback. Supervise una sesión activa mientras se reproduce contenido. Una sesión marcada como Direct playing envía el archivo sin modificar y consume prácticamente nada de CPU. Una sesión marcada como Transcoding muestra el motivo que seleccionó Jellyfin. Elimine ese motivo y la GPU no tendrá que trabajar.

Dos cambios eliminan la mayoría de las transcodificaciones. Configure la calidad de la aplicación cliente como Auto o con el valor máximo, porque un cliente que solicita 4 Mbps fuerza a recodificar un archivo de 20 Mbps, independientemente del códec que utilice. Después, use una aplicación cliente nativa en lugar de una pestaña del navegador, porque el navegador es el reproductor más limitado que tiene y una aplicación nativa en el mismo televisor suele reproducir directamente el mismo archivo.

Los subtítulos basados en imágenes son la excepción que ningún ajuste del cliente puede solucionar. Los subtítulos PGS de una copia Blu-ray y VOBSUB de una copia DVD son imágenes, por lo que deben dibujarse sobre el propio vídeo. Esto implica recodificar completamente el flujo de vídeo. Los subtítulos de texto en SRT se envían al cliente como una pista independiente y no consumen recursos. Cuando sea posible, convertir las pistas de subtítulos a texto resulta más útil que añadir una GPU. El resto de la configuración del servidor se explica en la guía para ejecutar un servidor multimedia Jellyfin en un VPS.

La mayoría de los planes VPS no incluyen ninguna GPU

Los planes VPS estándar no incluyen una GPU. Ejecute esto en el servidor antes de planificar cualquier otra cosa.

lspci -nn | grep -Ei "3d|display|vga"

En un VPS KVM típico, este comando muestra un adaptador de pantalla virtual del hipervisor o no muestra nada útil. Ese dispositivo no puede codificar vídeo. Una GPU real sólo aparece cuando el proveedor asigna una tarjeta física a su instancia o le proporciona una parte de ella. Esos planes tienen un precio acorde. Qué cargas de trabajo justifican realmente pagar por un VPS con GPU explica quién debería pagar por una GPU y quién no.

Si no hay GPU, dé prioridad a la reproducción directa y considere la transcodificación por software como un caso excepcional. Una única transcodificación por software de 1080p H.264 exige muchos recursos, pero puede ejecutarse con algunos núcleos de CPU. Una transcodificación por software de 4K HDR con asignación de tonos no puede completarse en tiempo real en un VPS pequeño. Por eso, la transmisión se entrecorta mientras la CPU permanece al 100 por ciento.

Instalar el controlador de NVIDIA en el host

Jellyfin 10.11 documenta como requisito mínimo el controlador de NVIDIA 520.56.06 en Linux. Ubuntu incluye una herramienta auxiliar que selecciona un paquete compatible.

sudo ubuntu-drivers list --gpgpu
sudo ubuntu-drivers install --gpgpu
sudo reboot

--gpgpu selecciona la variante del controlador para servidores sin interfaz gráfica. Es la opción adecuada para un servidor multimedia porque el equipo no tiene entorno de escritorio. El comando de listado muestra las ramas disponibles. Puede fijar una por nombre, por ejemplo, sudo ubuntu-drivers install --gpgpu nvidia:570-server. Use una rama que aparezca realmente en el listado, no la que se muestra aquí.

La variante para servidores no siempre instala nvidia-smi. Instale el paquete de utilidades correspondiente a la rama que eligió, por ejemplo, sudo apt install nvidia-utils-570-server. Después, compruebe el controlador.

nvidia-smi

Si el resultado es correcto, muestra una tabla con la versión del controlador y la versión de CUDA en el encabezado, la tarjeta identificada por su nombre y una lista de procesos vacía. Aquí son frecuentes dos fallos. nvidia-smi: command not found significa que falta el paquete de utilidades, no el controlador. NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver significa que el módulo del kernel no está cargado. En una instalación nueva, casi siempre se debe a que todavía no ha reiniciado o a que Secure Boot impide cargar un módulo sin firma. Confirme que el módulo esté presente con lsmod | grep nvidia.

Instalar NVIDIA Container Toolkit

El controlador permite que el host use la GPU. Docker todavía no la pasará a un contenedor porque el contenedor no tiene ni los nodos de dispositivo ni las bibliotecas del controlador. NVIDIA Container Toolkit inyecta ambos elementos al iniciar el contenedor. Estos son los comandos de instalación de NVIDIA para Debian y Ubuntu.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Instalar el paquete no es suficiente porque hay que indicar a Docker que existe el runtime.

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

nvidia-ctk runtime configure escribe una entrada de runtime nvidia en /etc/docker/daemon.json. El reinicio es el paso que suele omitirse. Omitirlo produce el error más común de toda esta configuración. Pruebe la integración antes de modificar Jellyfin.

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Debe mostrar la misma tabla que mostró el host. Si falla con un error que indica que no se puede seleccionar un device driver con capacidades gpu, el daemon de Docker no conoce el runtime nvidia. En ese caso, vuelva a ejecutar el comando de configuración y reinicie el daemon.

Asigne la GPU al contenedor de Jellyfin en Docker Compose

Esta es la sintaxis moderna de Compose y coincide con el ejemplo que publica Jellyfin.

services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    user: 1000:1000
    network_mode: host
    restart: unless-stopped
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/jellyfin/cache:/cache
      - /srv/media:/media:ro
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Inicie el contenedor y consulte la GPU directamente desde él.

docker compose up -d
docker compose exec jellyfin nvidia-smi

Si muestra la tabla de controladores desde dentro del contenedor, la GPU se ha pasado correctamente y cualquier problema restante está relacionado con la configuración de Jellyfin.

Estas cuatro líneas del archivo requieren una explicación. capabilities: [gpu] es obligatorio para el propio Compose. Si se omite, Compose rechaza el servicio en lugar de iniciarlo sin GPU. NVIDIA_DRIVER_CAPABILITIES=all es importante porque el toolkit sólo monta las bibliotecas de vídeo en el contenedor cuando se solicita la capacidad de vídeo. La documentación de Jellyfin también indica que esta variable es necesaria para la imagen oficial. Sin ella, CUDA funciona, pero NVDEC no, y el registro de transcodificación muestra Cannot load libnvcuvid.so.1. network_mode: host es lo que utiliza el propio ejemplo de Jellyfin, porque el descubrimiento automático de clientes mediante el puerto UDP 7359 no funciona a través de una red bridge.

user: 1000:1000 es la última línea y no está relacionada con la GPU. Determina qué archivos puede leer Jellyfin en el montaje de medios. Si no coincide, la biblioteca aparece vacía en lugar de mostrar un error de permisos. Cómo asignan PUID y PGID un usuario del contenedor a los archivos del disco explica la numeración. Es la misma numeración que ya configuró si ejecuta la pila de Sonarr y Radarr en Docker Compose junto con este contenedor.

Por qué la mayoría de los tutoriales todavía escriben runtime: nvidia

La forma anterior aparece en casi todas las guías que encontrará y no es incorrecta. Es una cuestión histórica. El paquete nvidia-docker2 original registraba un runtime OCI llamado nvidia, por lo que la única forma de proporcionar una GPU a un contenedor era --runtime=nvidia más NVIDIA_VISIBLE_DEVICES. Docker 19.03 añadió el indicador --gpus y una API adecuada para solicitar dispositivos. Compose tardó más en adaptarse y, cuando lo hizo, la solicitud de dispositivos se incluyó en deploy.resources.reservations.devices, una clave que la mayoría de las personas había aprendido a ignorar porque deploy solía referirse a Docker Swarm.

Por eso, ambas formas funcionan actualmente y el ejemplo publicado por Jellyfin incluye las dos a la vez. Mantener runtime: nvidia no tiene ningún coste y hace que el archivo funcione con versiones anteriores de Compose. Si conserva sólo runtime: nvidia y elimina el bloque deploy, debe mantener NVIDIA_VISIBLE_DEVICES=all, porque esa ruta heredada lee la variable de entorno para decidir qué dispositivos inyectar y no tiene ninguna solicitud de dispositivos alternativa que consultar.

Activar la transcodificación mediante hardware NVIDIA en Jellyfin

Hasta ahora, nada ha indicado a Jellyfin que use la tarjeta. Vaya a Dashboard, después a Playback y luego a Transcoding. Configure Hardware acceleration como Nvidia NVENC. Marque Enable hardware encoding. De lo contrario, Jellyfin decodifica en la GPU y después codifica en la CPU. Este estado intermedio puede resultar confuso: la GPU muestra actividad, pero la CPU sigue trabajando intensivamente.

Active enhanced NVDEC decoder para alternar entre la ruta NVDEC actual y la ruta CUVID antigua. Déjelo activado. El procesamiento de Dolby Vision necesita esta opción para usar NVDEC.

En Enable hardware decoding for, marque sólo los códecs que la tarjeta pueda decodificar realmente. Esta es la opción que suele configurarse mal. Marcar AV1 en una tarjeta sin decodificador AV1 no genera ningún mensaje de error. Jellyfin solicita una decodificación por hardware, no la obtiene y vuelve a la decodificación por software. Como resultado, el uso de la CPU es alto y la GPU permanece casi inactiva. Esto parece exactamente un fallo del passthrough.

Hay otra limitación que se aplica a toda la página: la aceleración por hardware sólo funciona con la compilación incluida de jellyfin-ffmpeg. Si configuró la ruta de FFmpeg para usar un FFmpeg del sistema, obtendrá una aceleración parcial o ninguna.

Qué códecs puede decodificar y codificar tu generación de GPU

Estos son los límites que documenta Jellyfin para NVENC y NVDEC. La decodificación y la codificación son capacidades independientes, y una tarjeta puede admitir una sin admitir la otra.

• H.264 de 8 bits: todas las GPU de NVIDIA con NVENC y NVDEC lo decodifican y codifican.
• HEVC de 8 bits: decodificación y codificación desde Maxwell de segunda generación (GM206) y posteriores.
• HEVC de 10 bits: decodificación desde Maxwell de segunda generación y posteriores, pero codificación sólo desde Pascal y posteriores.
• AV1: decodificación desde Ampere y posteriores, y codificación desde Ada Lovelace y posteriores.

La diferencia con HEVC de 10 bits es la que más problemas causa en la práctica. Una tarjeta de la generación Maxwell decodifica en la GPU tu archivo 4K HDR y después no puede codificar una salida de 10 bits, por lo que Jellyfin codifica H.264 de 8 bits. El archivo se sigue reproduciendo y, de todos modos, es la opción correcta para la mayoría de los clientes. La codificación AV1 rara vez es lo que necesitas en 2026, independientemente de la tarjeta, porque la compatibilidad de los clientes con la decodificación AV1 todavía es limitada y existe una transcodificación para llegar a un cliente que ya tenía problemas.

Por qué el tone mapping vuelve a saturar la GPU silenciosamente

El tone mapping de HDR (alto rango dinámico) a SDR (rango dinámico estándar) es el ajuste que consume inesperadamente el presupuesto de la GPU, y la razón es arquitectónica. La decodificación se ejecuta en NVDEC. La codificación se ejecuta en NVENC. El tone mapping no se ejecuta en ninguno de los dos: es un filtro CUDA que se ejecuta en los núcleos de shaders, la parte de propósito general de la GPU que también ejecuta cargas de computación. Por tanto, un flujo 4K HDR que necesita tone mapping utiliza el decodificador y el codificador, y además carga los shaders.

Jellyfin documenta el tone mapping con CUDA como disponible en cualquier GPU NVIDIA que pueda decodificar HEVC de 10 bits. Esto significa que la casilla aparece y funciona en tarjetas que no pueden mantener ese procesamiento en 4K. El síntoma es un flujo que se inicia, entra en búfer y nunca se estabiliza, mientras nvidia-smi indica que el codificador apenas está ocupado.

Por eso conviene supervisar por separado la carga de los shaders.

nvidia-smi dmon -s u

Esto muestra una línea por segundo con columnas independientes para sm, enc y dec. Un valor bajo de enc y dec junto a un valor alto de sm significa que los bloques de función fija están prácticamente inactivos y que los shaders son el cuello de botella. En ese caso, el coste procede del tone mapping, del escalado o de la inserción permanente de subtítulos. La ruta CUDA también gestiona Dolby Vision profile 5 con zero copy. Esto es importante porque, sin zero copy, los fotogramas salen a la memoria del sistema y vuelven entre los pasos de filtrado. Ese recorrido de ida y vuelta consume ancho de banda en cada fotograma.

Qué limita realmente el tope de sesiones NVENC de las GPU de consumo

[
  {
    "label": "GeForce RTX 5090",
    "nvenc_engines": 3,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4090",
    "nvenc_engines": 2,
    "max_encode_sessions": 12
  },
  {
    "label": "GeForce RTX 4060",
    "nvenc_engines": 1,
    "max_encode_sessions": 12
  }
]

Esas son las cifras publicadas por NVIDIA en su matriz a agosto de 2026, no mediciones realizadas aquí. Una tarjeta GeForce está limitada a 12 sesiones de codificación simultáneas, independientemente del modelo. El límite está en el controlador, no en el silicio, y NVIDIA lo ha aumentado varias veces a lo largo de los años. Por eso, consulte la matriz actual en lugar de una publicación antigua de un foro. El número de motores sí cambia con la tarjeta: la GeForce RTX 5090 tiene 3 motores NVENC, mientras que la GeForce RTX 4060 tiene 1. Más motores significan un mayor rendimiento de codificación en paralelo, no un límite de sesiones más alto.

El límite cuenta las sesiones de codificación, por lo que sólo cuenta los streams transcodificados. La reproducción directa y el remuxing nunca abren una sesión de codificación. Las tarjetas de centros de datos, como la L4, aparecen como no restringidas en la misma matriz. Además, una tarjeta de centro de datos suele ser la que ofrece un plan de GPU VPS, por lo que este límite afecta principalmente a los servidores domésticos.

Cuando se alcanza el límite, la transcodificación falla y el registro de FFmpeg contiene OpenEncodeSessionEx failed: out of memory (10). El mensaje menciona la memoria, pero un rechazo por límite de sesiones devuelve el mismo código. Por eso, compruebe el número de streams simultáneos antes de buscar una fuga de VRAM. En la práctica, la mayoría de los usuarios alcanzan antes el límite de tone mapping o el ancho de banda de subida, mucho antes de llegar a la sesión doce.

Demuestre que la GPU está realizando la transcodificación; no confíe en la configuración

Una configuración guardada no es una prueba. Reproduzca un archivo que sepa que obliga a transcodificar y realice estas tres comprobaciones.

1. Abra Dashboard y, después, Playback. La sesión activa debe indicar Transcoding y mostrar el motivo. Si indica Direct playing, no se está realizando ninguna transcodificación y está probando el archivo equivocado.
2. Abra Dashboard y, después, Logs. Abra el registro FFmpeg.Transcode más reciente. Una transcodificación por hardware muestra -hwaccel cuda y -hwaccel_output_format cuda en la línea de comandos, con h264_nvenc o hevc_nvenc como codificador. Si aparece libx264, la transcodificación se realiza por software, independientemente de lo que indique la página de configuración.
3. Ejecute nvidia-smi en el host mientras continúa la reproducción. Debe aparecer un proceso de /usr/lib/jellyfin-ffmpeg/ffmpeg con memoria de GPU asignada, y nvidia-smi dmon -s u debe mostrar valores distintos de cero en las columnas enc y dec.

Realice la tercera comprobación en el host, no dentro del contenedor. nvidia-smi dentro de un contenedor suele mostrar una lista de procesos vacía porque no puede ver los ID de proceso del exterior de su propio espacio de nombres, aunque los valores de utilización sigan mostrándose correctamente. Una lista de procesos vacía dentro del contenedor no indica un fallo.

Cuando recurre al software sin informarle

Jellyfin intenta mantener la reproducción. Cuando una ruta de hardware no está disponible, cambia al software en lugar de interrumpir la transmisión. Por eso, las señales fiables son la carga de CPU y el registro de FFmpeg, no un aviso de error.

Cannot load libnvcuvid.so.1 en el registro de transcodificación significa que la biblioteca del decodificador nunca se montó en el contenedor. Configure NVIDIA_DRIVER_CAPABILITIES=all y vuelva a crear el contenedor, porque un cambio de entorno requiere docker compose up -d para reconstruirlo. Un simple reinicio conserva la configuración anterior.

No capable devices found de h264_nvenc significa que FFmpeg llegó a la biblioteca del codificador, pero no encontró ninguna tarjeta utilizable. Compruebe docker compose exec jellyfin nvidia-smi de nuevo, porque normalmente esto indica que se eliminó la reserva del dispositivo o que el contenedor se volvió a crear a partir de un archivo obsoleto.

Una carga alta de CPU con una GPU inactiva significa que la decodificación está fallando sin mostrar errores. Desactive los códecs que su generación de hardware no puede decodificar. Después, vuelva a reproducir el mismo archivo y revise de nuevo el registro de FFmpeg para comprobar si aparece -hwaccel cuda.

Si una transcodificación comienza y después se bloquea con contenido 4K HDR, mientras que 1080p funciona correctamente, se ha alcanzado el límite del tone mapping. No se trata de una instalación dañada. Confírmelo con la columna sm de nvidia-smi dmon -s u. Después, reduzca la resolución solicitada por el cliente o mantenga los archivos 4K HDR en clientes que puedan reproducirlos directamente.

FAQ

¿Por qué Jellyfin sigue usando la CPU después de activar NVENC?

Compruebe el registro más reciente de FFmpeg.Transcode en Dashboard y, después, en Logs. Si muestra libx264, no se usó ninguna ruta de hardware, lo que normalmente significa que el contenedor no puede ver la GPU. Ejecute docker compose exec jellyfin nvidia-smi para confirmarlo. Si muestra h264_nvenc pero la CPU sigue ocupada, la decodificación se está ejecutando por software. Esto ocurre cuando seleccionó un códec que la tarjeta no puede decodificar o cuando dejó desactivada la opción Enable hardware encoding, de modo que sólo la mitad del flujo pasó a la GPU.

¿Sigue siendo necesaria la línea runtime: nvidia en Docker Compose?

No, si tiene el bloque deploy.resources.reservations.devices y una versión actual de Docker Compose. El bloque es el formato moderno para solicitar dispositivos y realiza la misma función. runtime: nvidia es la forma antigua de la época de nvidia-docker2. Todavía funciona y el ejemplo publicado por Jellyfin mantiene ambas formas. Mantener las dos no causa problemas. Si mantiene sólo runtime: nvidia, también debe mantener NVIDIA_VISIBLE_DEVICES=all, porque esa forma no incluye una solicitud de dispositivo de la que leer la lista y obtiene los dispositivos del entorno.

¿Cuántos streams puede transcodificar simultáneamente una GPU NVIDIA?

La matriz publicada por NVIDIA limita las tarjetas GeForce a doce sesiones de codificación simultáneas en agosto de 2026. Las tarjetas para centros de datos aparecen como no limitadas. Ese límite rara vez es el factor que detiene el sistema. La conversión de HDR a SDR mediante tone mapping se ejecuta en los núcleos de shaders, no en NVENC. Por eso, unos pocos streams 4K HDR agotarán los shaders mucho antes de que importe el contador de sesiones. Mida su caso con nvidia-smi dmon -s u y observe la columna sm, no el número de sesiones.

¿Puedo usar transcodificación por hardware en un VPS sin GPU?

No. La codificación necesita el bloque NVENC físico, y lspci -nn | grep -Ei "3d|display|vga" en un VPS estándar sólo muestra un adaptador de pantalla virtual del hipervisor. La opción práctica en un plan sin GPU es evitar las transcodificaciones: aumente a Auto la calidad configurada en el cliente, use una aplicación cliente nativa en lugar de un navegador y convierta las pistas de subtítulos basadas en imágenes a texto para que no fuercen una nueva codificación de vídeo.

¿Por qué 4K HDR se reproduce con interrupciones si 1080p se transcodifica correctamente?

Las dos cargas de trabajo usan partes distintas de la tarjeta. Una transcodificación 1080p SDR sólo realiza decodificación y codificación, ambas en hardware de función fija. Un stream 4K HDR añade tone mapping, que es un filtro CUDA ejecutado en los núcleos de shaders, además de un fotograma mucho mayor que debe escalarse. Que nvidia-smi dmon -s u muestre valores bajos en enc y dec junto a un valor alto en sm lo confirma. Ese patrón significa que los bloques de función fija están inactivos y que el límite está en los núcleos de propósito general.