Guía para evitar problemas al instalar Docker 2025: de permission denied a ejecución correcta

La tercera vez que instalé Docker: la primera falló por WSL 2, la segunda el daemon no arrancaba, y cuando por fin quedó instalado, docker ps devolvió permission denied.

Instalar Docker debería ser sencillo: descargas el instalador, doble clic, siguiente. Pero en Windows hay que lidiar con WSL 2 y Hyper-V; en Mac distinguir entre Intel y Apple Silicon; en Linux, con dependencias y permisos de grupo. Cada plataforma tiene su propio asiento reservado en la trampa.

Este artículo es el repaso después de pisar todas esas minas. Reuní los más de 10 problemas más frecuentes en Windows, Mac y Linux, cada uno con soluciones actualizadas a 2025 (sí, muchos tutoriales de 2020-2022 ya están obsoletos). ¿En qué plataforma estás y qué error ves? Sigue leyendo; seguro hay algo para ti.

Problemas frecuentes en Windows

En Windows, instalar Docker suele ser luchar contra WSL 2 y Hyper-V. Docker Desktop exige ahora el backend WSL 2; si tu versión del sistema no cumple o la virtualización está desactivada, prepárate para mensajes de error crípticos.

Problema 1: instalación incompleta de WSL 2

Es el más común en Windows. Al instalar Docker Desktop, aparece un aviso de WSL 2 installation is incomplete y no dice mucho más.

El error se ve así:

Docker Desktop requires WSL 2 backend
WSL 2 installation is incomplete

La raíz suele ser una de tres: Windows demasiado antiguo (por debajo de 10.0.19041), WSL no activado o virtualización desactivada en la BIOS.

Cómo arreglarlo:

Primero, comprueba la versión de Windows. Pulsa Win+R, escribe winver y mira el número de build. Necesitas al menos Windows 10 22H2 (build 19045) o Windows 11 23H2 (build 22631+). Si no llegas, actualiza el sistema.

Segundo, activa WSL. Ve a Panel de control → Programas y características → Activar o desactivar las características de Windows, marca Subsistema de Windows para Linux y Plataforma de máquina virtual. Reinicia; no te saltes este paso.

Tercero, actualiza WSL. Tras reiniciar, abre PowerShell como administrador y ejecuta:

wsl --update
wsl --set-default-version 2

La primera línea actualiza WSL (necesitas 2.1.5+); la segunda establece WSL 2 como predeterminado.

Si aún falla, toca entrar en la BIOS. Reinicia, pulsa Del o F2 (según la placa), busca Virtualization Technology o Intel VT-x/AMD-V y ponlo en Enabled. Intel lo llama VT-x; AMD, AMD-V; es lo mismo.

Problema 2: conflicto con Hyper-V

A veces verás este error extraño:

HCS_E_HYPERV_NOT_INSTALLED
Docker Desktop - Unexpected WSL error

Significa que Hyper-V no está instalado o choca con otro software de virtualización. Docker Desktop depende de Hyper-V (o de WSL 2); si también tienes VMware o VirtualBox, puede haber conflicto.

Cómo arreglarlo:

Si Hyper-V no está activo, en Características de Windows marca Hyper-V con todas las subopciones y reinicia. Ojo: Windows Home no soporta Hyper-V; solo puedes usar el backend WSL 2.

Si usas VMware o VirtualBox a la vez, tendrás que elegir. Desde la 4.x, Docker Desktop apuesta por WSL 2, que suele convivir mejor. VMware Workstation 15.5+ en teoría convive con Hyper-V, pero en la práctica sigue habiendo pequeños problemas.

Lo más práctico: Docker Desktop (WSL 2) para desarrollo; VMware/VirtualBox para producción o pruebas en VM, separados.

Problema 3: permisos de instalación insuficientes

Este error suele salir durante la instalación:

Installation Failed
Component CommunityInstaller.EnableFeaturesAction failed

Causa simple: no ejecutaste el instalador como administrador, o el antivirus lo bloqueó.

Cómo arreglarlo:

Clic derecho en el instalador de Docker Desktop → Ejecutar como administrador. Si el firewall o el antivirus preguntan, permite la acción.

Detalle fácil de olvidar: espacio en C:. Docker Desktop necesita al menos 10 GB libres; con muchas imágenes ocupará más. Si C: va justo, puedes cambiar después la ruta de datos de Docker, pero es otro tema.

Si es un PC corporativo con políticas de grupo, puede que no puedas instalar. Habla con IT o instala Docker Engine en el subsistema Linux (sin interfaz gráfica).

Problemas frecuentes en Mac

En Mac suele ir más fluido, pero desde M1/M2 hay nuevas trampas. La más típica: descargar la versión equivocada — Intel en Apple Silicon o al revés.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Problema 1: compatibilidad con chips M1/M2

El síntoma es claro: el icono de Docker Desktop no aparece en la barra de menú, o aparece pero se queda en Docker Desktop is starting… sin terminar. En Terminal, docker devuelve:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Lo más probable es que descargaste el paquete incorrecto. En la web de Docker hay dos versiones: Mac with Apple chip y Mac with Intel chip; si te equivocas, no arranca.

Cómo arreglarlo:

Confirma el chip. Icono de Apple → Acerca de este Mac → Chip. Si dice Apple M1 o Apple M2, necesitas Apple Silicon; si dice Intel Core, la versión Intel.

Si te equivocaste, desinstala por completo. En Terminal:

# Desinstalar Docker Desktop
/Applications/Docker.app/Contents/MacOS/uninstall

# Eliminar archivos de configuración residuales
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

Estos comandos borran Docker y su caché. Vuelve a descargar la versión correcta e instala.

Detalle: en Mac M1/M2 hace falta Rosetta 2 para algunas imágenes x86. Si no lo tienes:

softwareupdate --install-rosetta

Reinicia Docker Desktop; debería arrancar con normalidad.

Problema 2: el daemon se queda en Starting…

A veces Docker Desktop arranca, el icono aparece, pero se queda en Starting… Activity Monitor muestra procesos de Docker en ejecución, pero no puedes usarlo.

Suele ser configuración dañada o un proceso que ocupa los puertos de Docker.

Cómo arreglarlo:

Primero, restablece Docker Desktop. Icono Docker → Troubleshoot → Reset to factory defaults. Borra contenedores, imágenes y configuración. Si tienes imágenes importantes, haz copia antes.

Si no basta, revisa conflictos de puerto. Docker usa 2375 y 2376 por defecto:

# Ver qué ocupa el puerto
lsof -i :2375
lsof -i :2376

# Si hay salida, anota el PID y mata el proceso
kill -9 <PID>

Reinicia Docker Desktop.

Opción más drástica: borrar los archivos de la VM.

rm -rf ~/Library/Containers/com.docker.docker/Data/vms

Fuerza a Docker a recrear el entorno virtual. Al reiniciar, crea una VM nueva.

Problema 3: permiso denegado al montar archivos

Al montar un directorio local en un contenedor:

Error response from daemon: Mounts denied:
The path /Users/yourname/project is not shared from the host and is not known to Docker.

Docker no tiene permiso para acceder a esa ruta. macOS es estricto con la privacidad; por defecto solo ciertas rutas están permitidas.

Cómo arreglarlo:

Docker Desktop → Settings → Resources → File Sharing, añade el directorio con el botón +. Por defecto suelen estar /Users, /Volumes, /private, /tmp, pero subcarpetas a veces hay que añadirlas.

Si sigue fallando: Preferencias del sistema → Seguridad y privacidad → Privacidad → Acceso completo al disco, y marca Docker Desktop. En macOS 14.3+ las reglas son más estrictas; no omitas este paso.

Si montas un disco externo o una carpeta de red, configúralo en Docker. Los discos externos suelen estar bajo /Volumes; añádelos.

Problemas frecuentes en Linux

En Linux, instalar Docker debería ser lo más directo — Docker nació para Linux. En la práctica, permisos y dependencias siguen siendo trampas.

Problema 1: Permission Denied (el más frecuente)

Casi todo principiante en Linux lo ve. Tras instalar, ejecutas docker ps con ilusión y aparece:

docker: Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/...":
dial unix /var/run/docker.sock: connect: permission denied.

Tanta línea roja desconcierta. El daemon corre como root y tu usuario no puede usar el socket /var/run/docker.sock.

Cómo arreglarlo:

Añade tu usuario al grupo docker:

sudo usermod -aG docker $USER

Eso añade el usuario actual ($USER) al grupo docker (-aG docker). Pero no termina ahí.

El cambio de grupo no es inmediato; cierra sesión o actualiza el grupo:

newgrp docker

O cierra sesión y vuelve a entrar. Muchos se quedan aquí: cambian el grupo sin reiniciar sesión, el error continúa y creen que el método no sirve.

Comprueba que aplicó:

groups

Si aparece docker, listo. Prueba docker ps de nuevo.

Pero hay un riesgo de seguridad: el grupo docker equivale a privilegios de root — Docker puede leer todo el sistema de archivos. En desarrollo personal suele bastar; en producción, piénsalo dos veces.

Si aún falla, revisa el socket:

ls -l /var/run/docker.sock

Debería ser srw-rw---- 1 root docker. Si no:

sudo chmod 666 /var/run/docker.sock

Es temporal; tras reiniciar se pierde. Lo correcto sigue siendo el grupo docker.

Problema 2: dependencias faltantes (Ubuntu/Debian)

Suele aparecer al instalar:

docker-desktop : Depends: docker-ce-cli but it is not installable
The following packages have unmet dependencies:
 docker-desktop : Depends: pass but it is not installable
                  Depends: uidmap but it is not installable
                  Depends: gnome-terminal but it is not installable

Parece que faltan muchos paquetes; en realidad no añadiste el repositorio oficial de Docker. El apt por defecto no tiene Docker o trae versiones viejas.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Cómo arreglarlo (ejemplo Ubuntu):

Desinstala versiones antiguas si las hay:

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

Configura el repositorio oficial — paso que muchos tutoriales omiten o resumen mal:

# Actualizar índice apt
sudo apt-get update

# Instalar dependencias necesarias
sudo apt-get install ca-certificates curl gnupg lsb-release

# Añadir clave GPG oficial de Docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Configurar repositorio Docker
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

En la última línea, $(lsb_release -cs) detecta el codename de Ubuntu (jammy, focal, etc.). En Linux Mint puede haber trampa: Mint se basa en Ubuntu pero con otro número de versión. Mira /etc/os-release y usa el valor de UBUNTU_CODENAME, no el de Mint.

Tras añadir el repo, actualiza e instala:

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

Esta vez descarga desde Docker oficial y resuelve dependencias. Comprueba con docker --version.

Problema 3: el daemon no arranca

Tras instalar, al ejecutar comandos:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Similar a Mac, pero en Linux el daemon lo gestiona systemd; el diagnóstico cambia.

Cómo arreglarlo:

Estado del servicio:

sudo systemctl status docker

Si muestra inactive (dead) o failed, no está en marcha o falló al arrancar:

sudo systemctl start docker
sudo systemctl enable docker  # arranque automático

Si falla el arranque, mira los logs:

sudo journalctl -u docker.service -n 50

Suelen mostrar la causa concreta.

Subproblemas frecuentes:

Conflicto con SELinux (CentOS/RHEL):
Si los logs mencionan SELinux, prueba desactivarlo temporalmente:

sudo setenforce Permissive

Es temporal; al reiniciar vuelve. Para desactivarlo de forma permanente edita /etc/selinux/config, pero en producción es mejor ajustar políticas que apagar SELinux.

Error de sintaxis en la configuración:
Si tocaste /etc/docker/daemon.json, valida el JSON. Una coma de más o una comilla de menos impiden el arranque. Usa jsonlint o una herramienta online.

Firewall:
Algunas distros bloquean Docker. Prueba desactivar el firewall:

sudo systemctl stop firewalld  # CentOS/RHEL
sudo ufw disable              # Ubuntu

Si arranca sin firewall, configura reglas que permitan Docker.

Problema 4: conflicto de puertos

Menos común, pero molesto:

Error starting daemon: error initializing graphdriver: driver not supported
bind: address already in use

Suele ser que 2375 o 2376 están ocupados, o hay conflicto al configurar acceso remoto.

Cómo arreglarlo:

Comprueba puertos:

sudo netstat -tulnp | grep 2375
sudo netstat -tulnp | grep 2376

Si hay salida, anota el PID y mata el proceso:

sudo kill -9 <PID>

Para acceso remoto (no recomendado por seguridad), cambia el puerto en /etc/docker/daemon.json:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2376"]
}

Escuchar solo en 127.0.0.1 es más seguro. Si escuchas en todas las interfaces (0.0.0.0), usa TLS; no lo dejes abierto.

Tras cambiar la configuración:

sudo systemctl daemon-reload
sudo systemctl restart docker

Trampa: si configuras hosts en daemon.json y en el unit de systemd, chocan. Revisa /lib/systemd/system/docker.service; si ExecStart tiene -H, coméntalo y deja hosts solo en daemon.json.

Problemas generales y buenas prácticas

Sea cual sea tu plataforma, tras instalar Docker conviene unos pasos comunes de verificación y configuración; te ahorran dolores después.

Verificar que la instalación funciona

No te lances a usarlo sin comprobar. Ejecuta:

# Ver versión de Docker
docker --version

# Ver versión de Docker Compose (integrado en Docker moderno)
docker compose version

# Contenedor de prueba (Hello World oficial)
docker run hello-world

# Información del sistema
docker info

docker run hello-world descarga una imagen pequeña y la ejecuta; si ves Hello from Docker!, todo va bien. docker info muestra driver de almacenamiento, logs, número de contenedores; muy útil cuando algo falla.

Configurar aceleración de mirrors (imprescindible en China)

Sin mirrors, en China tirar de imágenes puede ser lentísimo. Docker Hub desde allí es inestable y a menudo hace timeout.

Edita la configuración (Linux: /etc/docker/daemon.json; Windows/Mac: pestaña Docker Engine en Docker Desktop):

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://registry.docker-cn.com"
  ]
}

Guarda y reinicia Docker:

# Linux
sudo systemctl restart docker

# Mac/Windows: clic derecho en el icono Docker → Restart

Comprueba que aplicó:

docker info | grep -A 5 "Registry Mirrors"

Deberías ver las URLs configuradas.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Los mirrors públicos en China también fallan a veces; configura varios de respaldo. Algunos requieren cuenta (p. ej. el servicio de Alibaba Cloud) pero van más rápido.

Limitar el tamaño de los logs (evitar llenar el disco)

Por defecto los logs de contenedor no tienen límite; contenedores de larga duración pueden generar decenas de GB y dejar el disco lleno. Me pasó una vez: el servidor se quedó sin espacio y todos los contenedores cayeron.

En daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Cada contenedor: máximo 10 MB por archivo, conserva los 3 más recientes. Al superar 10 MB rota y borra logs antiguos.

Para conservar logs a largo plazo, mejor ELK, Loki u otro sistema centralizado que el disco local.

Configurar el driver de almacenamiento

El rendimiento varía mucho según el driver. En Linux, overlay2 es el recomendado y el más rápido hoy. Muchos sistemas modernos ya lo usan; versiones viejas pueden tener devicemapper o aufs, mucho más lentos.

Comprueba el driver actual:

docker info | grep "Storage Driver"

Si no es overlay2, añade en daemon.json:

{
  "storage-driver": "overlay2"
}

Cambiar el driver requiere reiniciar Docker y borra todos los contenedores e imágenes; haz copia de lo importante antes.

Reglas que aprendí a pulso

Experiencia después de muchos tropiezos:

1. Prioriza la documentación oficial. docs.docker.com está clara; muchos tutoriales en buscadores son copias con errores. Ante dudas, documentación oficial primero.

2. Mira la fecha del tutorial. Docker cambia rápido; guías de 2020-2022 suelen estar desactualizadas. Prefiere material de los últimos uno o dos años.

3. Usa docker info y los logs. docker info para configuración; docker logs <ID> para salida del contenedor; journalctl -u docker.service (Linux) para el daemon. El 90 % de pistas están en los logs.

4. No instales Docker Desktop dentro de una VM. Docker Desktop ya virtualiza; anidar virtualización va mal y da errores raros. En VMs, instala Docker Engine directamente.

5. No ejecutes contenedores como root si puedes evitarlo. Es buena práctica de seguridad; muchos usan root por comodidad, pero en producción no lo hagas.

Lista rápida de diagnóstico

¿Problema con Docker y no sabes por dónde empezar? Sigue este orden; localizarás el 90 % de casos frecuentes.

Paso 1: entorno básico

• ¿Versión reciente? docker --version; mejor la estable más nueva
• ¿Sistema compatible? Windows 10 19045+/Win11 22631+, macOS 13+, Ubuntu 20.04+
• ¿Espacio en disco? Al menos 10 GB; df -h (Linux/Mac) o Explorador de archivos (Windows)

Paso 2: permisos y grupos (Linux/Mac)

• ¿Estás en el grupo docker? groups debe mostrar docker
• ¿Reiniciaste sesión tras cambiar el grupo? Muchos lo omiten; usa newgrp docker o cierra sesión
• ¿Permisos del socket correctos? ls -l /var/run/docker.sock → srw-rw---- 1 root docker

Paso 3: servicios y procesos

• ¿Corre el daemon?
  • Linux: sudo systemctl status docker
  • Mac: Activity Monitor, busca Docker
  • Windows: Administrador de tareas, Docker Desktop
• ¿Conflicto de puertos? netstat -tulnp | grep docker (Linux) o lsof -i :2375 (Mac)
• ¿Firewall? Desactívalo temporalmente (sudo systemctl stop firewalld o sudo ufw disable)

Paso 4: configuración

• ¿JSON válido en daemon.json? Valídalo o borra el archivo y reinicia para probar
• ¿hosts duplicado? No configures a la vez en daemon.json y en systemd
• ¿Mirrors accesibles? ping registry.docker-cn.com o curl https://docker.m.daocloud.io

Paso 5: logs detallados

Paso clave; suelen tener el error exacto:

• Linux: sudo journalctl -u docker.service -n 50
• Mac: logs en ~/Library/Containers/com.docker.docker/Data/log/
• Windows: Visor de eventos → Registros de aplicaciones y servicios → Docker Desktop

Si no entiendes el log, copia el error completo y búscalo en Google en inglés; casi seguro alguien ya lo tuvo.

Paso 6: último recurso

En orden:

1. Restablecer Docker Desktop (Troubleshoot → Reset to factory defaults)
2. Desinstalar por completo y reinstalar (borra configuración y caché)
3. Comprobar si el antivirus bloquea (desactívalo temporalmente)
4. Probar otra versión (si la última falla, una estable anterior)

Si nada funciona, publica versión del sistema, versión de Docker y log completo en el foro oficial de Docker o Stack Overflow; la comunidad suele ayudar.

Conclusión

Instalar Docker es difícil y fácil a la vez. Difícil porque cada plataforma tiene sus trampas: WSL 2 y virtualización en Windows, chip en Mac, permisos y dependencias en Linux. Fácil porque los patrones se repiten; con la causa clara, los pasos suelen ser los mismos.

Los problemas de este artículo — permission denied, daemon que no arranca, dependencias faltantes — cubren el 80 % de errores de instalación. El 20 % restante son entornos raros; con logs, documentación y búsqueda en inglés también se resuelven.

Unos consejos finales:

Tras instalar, ejecuta docker run hello-world antes de usarlo en serio. En China, configura mirrors o las descargas irán lentas. Limita el tamaño de logs para no llenar el disco después.

Si algo falla, no entres en pánico: recorre la lista rápida; la mayoría se arregla solo. Si no, pide ayuda en el foro de Docker o Stack Overflow con error completo y versión del sistema, no con un ¿Docker no se instala, qué hago?

Pruébalo. Si este artículo te ayudó, compártelo con quien siga peleándose con la instalación. Menos trampas para todos, más tiempo para desarrollar.