Sign in Subscribe
7 min read jellyfin

Cómo instalar y configurar Jellyfin con Docker Compose en Ubuntu (guía completa)

Share
Cómo instalar y configurar Jellyfin con Docker Compose en Ubuntu (guía completa)

Si buscas una alternativa libre y sin suscripciones para gestionar tu propia biblioteca de series y películas, Jellyfin es exactamente lo que necesitas. En esta guía aprenderás a desplegarlo desde cero usando Docker Compose sobre Ubuntu, personalizarlo con temas y configurar la descarga automática de subtítulos — todo con los comandos y pasos necesarios para seguirla sin depender de ningún vídeo.

¿Qué es Jellyfin y por qué Docker Compose?

Jellyfin es un servidor multimedia de código abierto, una alternativa gratuita a Plex o Emby. Te permite organizar y reproducir tu biblioteca de vídeo, música e imágenes desde cualquier dispositivo en tu red local, o incluso desde fuera de casa.

Usar Docker Compose para desplegarlo tiene varias ventajas claras:

  • El servidor corre aislado del sistema, sin ensuciar dependencias
  • Actualizar Jellyfin se reduce a cambiar una línea y reiniciar el contenedor
  • La configuración queda definida en un fichero que puedes versionar o mover a otro servidor en minutos

Requisitos previos

  • Un sistema Ubuntu 22.04 o 24.04 (servidor o escritorio)
  • Usuario con privilegios sudo
  • Conexión a internet
  • Al menos 2 GB de RAM y espacio suficiente para tu biblioteca multimedia

1. Instalar Docker en Ubuntu

Si ya tienes Docker instalado, puedes saltar al paso 2.

Primero, elimina versiones antiguas o paquetes conflictivos:

sudo apt remove docker docker-engine docker.io containerd runc

Actualiza los repositorios e instala las dependencias necesarias:

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

Añade la clave GPG oficial de Docker:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Añade el repositorio oficial:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Instala Docker Engine y el plugin de Compose:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verifica que funciona:

docker --version
docker compose version

Evitar usar sudo en cada comando

Añade tu usuario al grupo docker para no tener que escribir sudo cada vez:

sudo usermod -aG docker $USER

Cierra la sesión y vuelve a entrar para que el cambio surta efecto. Puedes verificarlo con:

docker run hello-world

2. Crear la estructura de directorios

Antes de escribir el docker-compose.yml, organiza las carpetas donde Jellyfin guardará su configuración y tus archivos multimedia:

mkdir -p ~/jellyfin/{config,cache}
mkdir -p ~/jellyfin/media/{pelis,series,musica}

La estructura quedará así:

~/jellyfin/
├── config/        # Configuración interna de Jellyfin
├── cache/         # Caché de miniaturas y metadatos
├── media/
│   ├── pelis/
│   ├── series/
│   └── musica/
└── docker-compose.yml

Coloca tus archivos de vídeo en las carpetas correspondientes dentro de media/.

3. Crear el fichero docker-compose.yml

Entra en la carpeta de Jellyfin y crea el fichero:

cd ~/jellyfin
nano docker-compose.yml

Pega este contenido:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    network_mode: host
    environment:
      - JELLYFIN_PublishedServerUrl=http://localhost:8096
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./media:/media

Guarda con Ctrl+O, Enter y cierra con Ctrl+X.

¿Por qué network_mode: host? Jellyfin usa autodescubrimiento en la red local para que los clientes te encuentren automáticamente. Con el modo host esto funciona sin configuración adicional. Si prefieres usar puertos explícitos, puedes sustituir esa línea por:

    ports:
      - "8096:8096"   # HTTP
      - "8920:8920"   # HTTPS

4. Arrancar el servidor

Con el fichero listo, levanta el contenedor:

docker compose up -d

El parámetro -d lo ejecuta en segundo plano. Para comprobar que está corriendo:

docker ps

Deberías ver el contenedor jellyfin con estado Up. Para ver los logs en tiempo real si algo falla:

docker compose logs -f

5. Configuración inicial desde el navegador

Abre el navegador y ve a:

http://localhost:8096

Si lo estás instalando en un servidor remoto, sustituye localhost por la IP del servidor.

El asistente de configuración te pedirá:

  1. Idioma: Selecciona Español
  2. Usuario administrador: Crea tu usuario y contraseña
  3. Añadir biblioteca de medios: Selecciona el tipo (Películas, Series...) y apunta a la ruta dentro del contenedor, por ejemplo /media/pelis o /media/series
  4. Idioma de metadatos: Puedes configurarlo en Español/Castellano para que los títulos y descripciones se descarguen en tu idioma
Importante sobre la organización de archivos: Jellyfin escanea los metadatos automáticamente, pero necesita que los archivos estén bien nombrados. Para series, usa el formato NombreSerie/Temporada 01/NombreSerie - S01E01.mkv. Para películas, basta con NombrePelicula (Año)/NombrePelicula (Año).mkv.

6. Habilitar acceso remoto

Si quieres acceder a Jellyfin desde fuera de tu red local, ve a Panel de administración → Redes y asegúrate de que la opción "Permitir conexiones remotas" está activada.

Tendrás que abrir el puerto 8096 en el firewall de tu router (NAT/port forwarding) apuntando a la IP local de tu servidor. Para mayor seguridad, lo recomendable es poner un proxy inverso como Nginx o Caddy con HTTPS por delante, pero eso da para otra guía.

Errores comunes y cómo resolverlos

El contenedor arranca pero no puedo acceder al puerto 8096 Si usas network_mode: host y tienes UFW activo, comprueba que el puerto está permitido:

sudo ufw allow 8096/tcp

Jellyfin no encuentra mis archivos de vídeo Verifica que la ruta dentro del contenedor coincide con lo que configuraste en el volumen. Puedes entrar al contenedor para comprobarlo:

docker exec -it jellyfin ls /media

El contenedor no arranca y los logs muestran errores de permisos El contenedor corre con un usuario interno. Si las carpetas config o cache tienen permisos restrictivos, Jellyfin no puede escribir en ellas. Solución rápida:

chmod -R 755 ~/jellyfin/config ~/jellyfin/cache

Cómo actualizar Jellyfin Cuando salga una nueva versión, actualizar es tan sencillo como:

cd ~/jellyfin
docker compose pull
docker compose up -d

Vídeo explicativo si quieres seguir el procedimiento de forma visual.

7. Cambiar la apariencia con temas CSS

Jellyfin permite personalizar completamente su interfaz mediante CSS personalizado, sin tocar ningún fichero del servidor. Hay varios temas de la comunidad muy pulidos que transforman la apariencia por defecto en algo bastante más moderno.

Algunos de los más usados:

  • JellySkin — tema oscuro y limpio, muy popular, con buen soporte para móvil
  • Ultrachromic — minimalista, con fondo de color que se adapta al póster de cada contenido
  • Scyfin — inspirado en Spotify, con tipografía grande y navegación lateral
  • ElegantFin — destaca la información de actores y da más protagonismo a las carátulas

Para aplicar cualquiera de ellos el proceso es siempre el mismo:

  1. Ve al repositorio GitHub del tema que quieras (búscalo por su nombre en GitHub)
  2. Copia las líneas @import que indica su README
  3. En Jellyfin, ve a Panel de control → General
  4. Pega el código en el campo Código CSS personalizado
  5. Guarda y recarga el navegador con Ctrl + F5 para limpiar la caché

Por ejemplo, para JellySkin el código a pegar sería algo como:

@import url('https://cdn.jsdelivr.net/gh/AnonymousNP/Jellyskin@latest/jellyskin.css');
Nota: Los temas CSS solo afectan a la interfaz web. Los clientes de Android, iOS o TV tienen su propia apariencia y no se ven afectados por este CSS.

Si quieres ajustes más finos, puedes añadir tus propias reglas CSS debajo del @import. Por ejemplo, para cambiar el color de acento:

:root {
  --accent: #e5a00d;
}

8. Subtítulos automáticos con OpenSubtitles

Si ves contenido en versión original, buscar subtítulos manualmente para cada capítulo o película es tedioso. Jellyfin tiene un plugin oficial que se conecta a OpenSubtitles y los descarga automáticamente.

Instalar el plugin

  1. Ve a Panel de control → Catálogo de plugins
  2. Busca Open Subtitles e instálalo
  3. Reinicia Jellyfin para que el plugin quede activo:
docker compose restart

Crear una cuenta en OpenSubtitles

Regístrate gratis en opensubtitles.com. La cuenta gratuita permite hasta 20 descargas de subtítulos al día, que es más que suficiente para uso personal.

Configurar el plugin en Jellyfin

  1. Ve a Panel de control → Plugins → Open Subtitles
  2. Introduce tu usuario y contraseña de OpenSubtitles
  3. En las opciones de idioma, añade los idiomas que quieras (Español, Inglés...)
  4. Guarda los cambios

Descargar subtítulos para un contenido

Una vez configurado, puedes descargar subtítulos de dos formas:

Manualmente: En la película o episodio, haz clic en los tres puntos → Editar subtítulos → busca el idioma deseado y descarga el que mejor puntuación tenga.

Automáticamente al añadir contenido: En Panel de control → Biblioteca, activa la opción "Descargar subtítulos automáticamente" para cada biblioteca. Jellyfin los buscará y descargará al escanear contenido nuevo.

Consejo: Antes de descargar un subtítulo manualmente, comprueba la tasa de fotogramas (fps) del vídeo en "Información del archivo". Elegir un subtítulo con la misma tasa de fotogramas reduce mucho los problemas de sincronización.

Si el subtítulo va desincronizado

Durante la reproducción, haz clic en el icono de ajustes (rueda) y usa Desplazamiento de subtítulo para adelantar o retrasar el texto hasta que encaje con el audio. Es un ajuste en tiempo real que no modifica el fichero original.

Errores comunes y cómo resolverlos

El contenedor arranca pero no puedo acceder al puerto 8096 Si usas network_mode: host y tienes UFW activo, comprueba que el puerto está permitido:

sudo ufw allow 8096/tcp

Jellyfin no encuentra mis archivos de vídeo Verifica que la ruta dentro del contenedor coincide con lo que configuraste en el volumen. Puedes entrar al contenedor para comprobarlo:

docker exec -it jellyfin ls /media

El contenedor no arranca y los logs muestran errores de permisos El contenedor corre con un usuario interno. Si las carpetas config o cache tienen permisos restrictivos, Jellyfin no puede escribir en ellas. Solución rápida:

chmod -R 755 ~/jellyfin/config ~/jellyfin/cache

El plugin de OpenSubtitles no descarga nada Asegúrate de haber reiniciado el contenedor tras instalar el plugin. Si sigue sin funcionar, comprueba en los logs si hay errores de autenticación:

docker compose logs -f | grep -i subtitle

Cómo actualizar Jellyfin Cuando salga una nueva versión, actualizar es tan sencillo como:

cd ~/jellyfin
docker compose pull
docker compose up -d

Conclusión

Con esta guía tienes Jellyfin instalado, configurado, personalizado y con subtítulos automáticos, todo corriendo en un contenedor Docker que puedes mover o actualizar en segundos. Sin suscripciones, sin datos en servidores de terceros y con control total sobre tu biblioteca.

Jellyfin soporta además transcodificación por hardware, tiene clientes para Android, iOS, Fire TV, Kodi y más, y la comunidad detrás es muy activa. Hay mucho más que explorar: proxy inverso con HTTPS, transcodificación con GPU, sincronización con Sonarr y Radarr... pero eso da para sus propias guías.

Si tienes algún problema en cualquier paso, los logs de Docker son siempre el primer sitio donde mirar:

docker compose logs -f

Te dejo el vídeo por si quieres seguir de forma visual todo el proceso de personalización de Jellyfin.

Published by:

Rafa