Limpieza de Docker

La gestión del espacio en disco es crucial cuando trabajas con Docker: los contenedores detenidos, las imágenes antiguas, los volúmenes no utilizados, la caché de construcción y las redes huérfanas pueden acumularse con rapidez y ocupar mucho almacenamiento. Docker no elimina automáticamente estos recursos, así que conviene hacer limpiezas periódicas. En Docker, los volúmenes no se eliminan automáticamente cuando dejan de estar en uso; para limpiarlos, existen comandos específicos como docker volume prune. (docs.docker.com)

important

Esta guía cubre limpieza y liberación de espacio. Antes de borrar recursos, verifica si hay datos persistentes importantes en volúmenes o proyectos de Compose que quieras conservar. docker system prune elimina contenedores detenidos, redes no usadas, imágenes colgantes y caché de construcción; con --volumes, también puede limpiar volúmenes anónimos no usados. (docs.docker.com)

1. Qué suele ocupar espacio en Docker

Contenedores detenidos: siguen ocupando metadatos y capas asociadas.
Imágenes antiguas: especialmente las que ya no usa ningún contenedor.
Volúmenes no utilizados: pueden contener datos persistentes.
Redes huérfanas: no suelen ocupar mucho disco, pero sí dejan configuración acumulada.
Caché de construcción: puede crecer bastante si construyes imágenes con frecuencia. docker system prune la elimina como parte de su limpieza. (docs.docker.com)

validated

Antes de borrar nada, revisa el estado del consumo con docker system df. Si necesitas limpiar solo lo justo, usa los comandos prune específicos en lugar de un borrado global. (docs.docker.com)

2. Limpieza segura y recomendada

Estos comandos son la primera opción cuando quieres recuperar espacio sin entrar en operaciones agresivas.

Comando	Qué elimina	Cuándo usarlo
`docker container prune`	Contenedores detenidos	Cuando solo quieres limpiar contenedores ya parados. (docs.docker.com)
`docker image prune`	Imágenes colgantes	Cuando quieres borrar capas/imágenes sin etiqueta. (docs.docker.com)
`docker image prune -a`	Todas las imágenes no usadas por ningún contenedor	Cuando buscas una limpieza más profunda de imágenes. (docs.docker.com)
`docker volume prune`	Volúmenes locales no usados	Cuando necesitas recuperar espacio ocupado por datos persistentes ya no referenciados. Por defecto elimina solo volúmenes anónimos; con `-a` también elimina volúmenes nombrados no usados. (docs.docker.com)
`docker network prune`	Redes personalizadas no usadas	Cuando quieres limpiar redes huérfanas. Docker no elimina `bridge`, `host` ni `none`. (docs.docker.com)
`docker buildx prune`	Caché de build	Cuando el problema principal es la caché de compilación. (docs.docker.com)
`docker system prune`	Todo lo anterior, excepto volúmenes por defecto	Cuando quieres una limpieza general sin incluir volúmenes, salvo que añadas `--volumes`. (docs.docker.com)

Ejemplos mínimos

docker container prune
docker image prune
docker image prune -a
docker volume prune
docker network prune
docker system prune
docker system prune -a --volumes
docker buildx prune

warning

docker volume prune -a y docker system prune -a --volumes pueden borrar datos persistentes si esos volúmenes no están realmente en uso. Úsalos solo si has verificado que no necesitas esa información. (docs.docker.com)

3. Limpieza exhaustiva de Docker

critical

Esta sección es destructiva. El siguiente procedimiento puede eliminar contenedores, imágenes, volúmenes y redes no deseadas de forma irreversible. Si tienes datos importantes en volúmenes, respáldalos antes. (docs.docker.com)

Comando “nuclear”

([ -n "$(docker ps -aq)" ] && docker stop $(docker ps -aq) && docker rm $(docker ps -aq)); [ -n "$(docker images -q)" ] && docker rmi -f $(docker images -q); [ -n "$(docker volume ls -q)" ] && docker volume rm $(docker volume ls -q); NETWORKS=$(docker network ls --format '{{.Name}}' | grep -vE 'bridge|host|none'); [ -n "$NETWORKS" ] && docker network rm $NETWORKS; docker system prune -a --volumes -f; sudo rm -rf /var/lib/docker/volumes/*; sudo rm -rf /var/lib/containerd; sudo systemctl restart docker; echo -e "\n[+] Eliminación completada, comprobando almacenamiento...\n[*] Almacenamiento:\n$(df -h)"

Desglose por partes

3.1 Detener y eliminar contenedores

docker ps -aq lista todos los contenedores, activos y detenidos.
docker stop $(docker ps -aq) detiene los contenedores listados.
docker rm $(docker ps -aq) elimina los contenedores detenidos.
La condición [ -n "$(docker ps -aq)" ] evita ejecutar el bloque si no hay contenedores.

3.2 Eliminar imágenes

docker images -q lista los IDs de las imágenes locales.
docker rmi -f $(docker images -q) las borra forzadamente.
El uso de -f fuerza la eliminación incluso si existen referencias que lo permitan desde contenedores detenidos.

3.3 Eliminar volúmenes

docker volume ls -q lista todos los volúmenes.
docker volume rm $(docker volume ls -q) elimina todos los volúmenes listados.
Esto borra datos persistentes almacenados en volúmenes. En la práctica, equivale a una limpieza mucho más agresiva que docker volume prune. (docs.docker.com)

3.4 Eliminar redes personalizadas

docker network ls --format '{{.Name}}' lista nombres de redes.
grep -vE 'bridge|host|none' excluye las redes predeterminadas.
docker network rm $NETWORKS elimina las redes personalizadas huérfanas. Docker no prunea las redes del sistema (bridge, host, none). (docs.docker.com)

3.5 Limpieza general adicional

docker system prune -a --volumes -f limpia contenedores detenidos, redes no usadas, imágenes no usadas y volúmenes anónimos no usados. Por defecto, Docker evita eliminar volúmenes para no borrar datos por accidente. (docs.docker.com)

3.6 Borrado directo en el sistema de archivos

sudo rm -rf /var/lib/docker/volumes/*
sudo rm -rf /var/lib/containerd

Estos comandos omiten la API de Docker y actúan directamente sobre el almacenamiento del sistema. Son la parte más agresiva del proceso y pueden dejar el entorno en un estado delicado si la metadata no coincide con el estado real. Úsalos solo en situaciones excepcionales. (docs.docker.com)

3.7 Reinicio y verificación

sudo systemctl restart docker reinicia el servicio para que Docker recargue su estado.
df -h permite comprobar el espacio liberado.

4. Limpieza de proyectos con Docker Compose

Docker Compose gestiona aplicaciones multi-contenedor definidas en un archivo docker-compose.yml o compose.yml. Los comandos de limpieza aquí son más específicos y se aplican al proyecto actual. docker compose down detiene y elimina contenedores, redes, volúmenes e imágenes creados por up, y permite controlar qué recursos se retiran con opciones como --volumes, --rmi y --remove-orphans. (docs.docker.com)

4.1 Detener y eliminar el proyecto

docker compose down

Por defecto:

elimina los contenedores definidos en el archivo Compose;
elimina las redes definidas por el proyecto;
elimina la red por defecto del proyecto si se usa;
no elimina volúmenes externos ni volúmenes anónimos por defecto. (docs.docker.com)

4.2 Eliminar volúmenes del proyecto

docker compose down --volumes

Elimina los volúmenes nombrados declarados en el archivo Compose.
Elimina también los volúmenes anónimos asociados a los contenedores.
Los recursos marcados como external no se eliminan. (docs.docker.com)

4.3 Eliminar imágenes del proyecto

docker compose down --rmi all
docker compose down --rmi local

--rmi all: elimina todas las imágenes usadas por los servicios del proyecto.
--rmi local: elimina solo imágenes sin etiqueta personalizada. (docs.docker.com)

4.4 Eliminar contenedores huérfanos

docker compose down --remove-orphans

Úsalo cuando cambias el archivo Compose y quedan servicios que ya no existen definidos en él. --remove-orphans elimina esos contenedores sobrantes. (docs.docker.com)

4.5 Limpieza completa del proyecto

docker compose down --volumes --rmi all --remove-orphans

Este comando detiene y elimina:

contenedores del proyecto;
redes del proyecto;
volúmenes definidos en el Compose;
imágenes usadas por los servicios;
contenedores huérfanos asociados al proyecto. (docs.docker.com)

5. Checklist antes y después de limpiar

Antes de limpiar

Revisar qué ocupa espacio con docker system df. (docs.docker.com)
Confirmar si hay datos importantes en volúmenes. (docs.docker.com)
Verificar si el proyecto usa Docker Compose y si los volúmenes son externos. (docs.docker.com)
Elegir primero un comando específico antes de usar una limpieza global.

Después de limpiar

Comprobar espacio libre con df -h.
Verificar que Docker sigue funcionando correctamente.
Si usas Compose, volver a levantar solo lo necesario con docker compose up -d.

6. Buenas prácticas para no llenar el disco tan rápido

Usa limpiezas graduales: empieza por docker container prune, docker image prune o docker volume prune antes de una limpieza global. (docs.docker.com)
Protege los datos persistentes: prefiere volúmenes nombrados o bind mounts bien controlados, especialmente para bases de datos. docker compose down no elimina volúmenes externos. (docs.docker.com)
Mide el consumo periódicamente: revisa docker system df para detectar crecimiento anormal.
No uses -a ni --volumes sin revisar: son opciones útiles, pero elevan mucho el riesgo de borrar recursos todavía necesarios. (docs.docker.com)
Automatiza con criterio: en entornos de desarrollo o CI/CD, programa limpiezas frecuentes, pero no agresivas por defecto.
Evita depender del borrado manual en ****/var/lib/docker: mejor usar la CLI de Docker siempre que sea posible. (docs.docker.com)

7. Nota sobre `sudo` y el grupo `docker`

En muchos sistemas, ejecutar Docker requiere sudo o pertenecer al grupo docker. Si añades tu usuario a ese grupo, tendrás acceso al daemon sin escribir sudo, pero eso también implica un nivel de privilegio alto sobre el sistema. Trata ese acceso con la misma cautela que el acceso administrativo.

8. Resumen rápido

Para limpieza normal: docker container prune, docker image prune, docker volume prune, docker network prune. (docs.docker.com)
Para limpieza general: docker system prune o docker system prune -a --volumes. (docs.docker.com)
Para proyectos Compose: docker compose down --volumes --rmi all --remove-orphans. (docs.docker.com)
Para borrado extremo: usa el comando nuclear solo si entiendes el impacto completo.

- EOF -