Cómo liberar espacio en Docker con system prune, image prune y volume prune

Introducción

Si trabajás con Docker seguramente notaste que, con el tiempo, el disco se llena de imágenes, contenedores detenidos y volúmenes que ya no se usan. Esto pasa porque cada vez que construís una imagen, lanzás un contenedor o creás un volumen, Docker guarda esos recursos en el sistema de archivos. Cuando ya no los necesitás, siguen ocupando espacio hasta que los borrás explícitamente.

Este artículo está dirigido a desarrolladores, devops y cualquier persona que use Docker en su máquina local o en servidores y quiera recuperar espacio de forma segura. Aprenderás qué hace cada comando de poda, cómo usarlos con ejemplos concretos, qué salida esperás ver y, sobre todo, qué se borra para que no eliminés algo importante por accidente.

Al final vas a saber:

• Cuándo usar docker system prune vs los comandos más específicos.
• Qué filtros podés aplicar para conservar ciertos recursos.
• Cómo interpretar la salida y qué datos se eliminan realmente.
• Buenas prácticas para automatizar la limpieza sin riesgos.

¿Por qué Docker ocupa espacio con el tiempo?

Docker guarda tres tipos principales de objetos que pueden volverse huérfanos:

1. Imágenes: capas de sistemas de archivos que quedan sin ser referenciadas por ningún contenedor.
2. Contenedores: instancias detenidas o finalizadas que todavía existen en el motor.
3. Volúmenes: espacios de almacenamiento persistente que pueden quedar huérfanos cuando el contenedor que los usaba se borró.

Cada uno de estos objetos se almacena en el directorio de datos de Docker (por defecto /var/lib/docker en Linux). Si no los limpiás, el disco puede crecer sin control, especialmente en entornos de CI/CD donde se construyen muchas imágenes por día.

docker system prune: la limpieza general

El comando docker system prune es el más amplio. Elimina todos los recursos que estén "dangling" (huérfanos) y, si se le indica, también los que no estén en uso según ciertos criterios de tiempo.

Sintaxis básica

docker system prune

Al ejecutarlo sin opciones, Docker te pedirá confirmación y luego borrará:

• Todas las imágenes dangling.
• Todos los contenedores detenidos.
• Todas las redes no usadas por ningún contenedor.
• El caché de construcción (build cache).

No borra volúmenes ni imágenes que tengan al menos un contenedor asociado (incluso si ese contenedor está detenido).

Ejemplo con salida esperada

Supongamos que tenés algunas imágenes dangling y un par de contenedores detenidos. La salida sería algo como:

$ docker system prune
ADVERTENCIA: Esto eliminará:
- Todas las imágenes dangling
- Todos los contenedores detenidos
- Todas las redes no usadas
- El caché de construcción

¿Está seguro de que desea continuar? [y/N] y

Eliminando 2 imágenes dangling
Eliminando 3 contenedores detenidos
Eliminando 1 red
Liberados 2,1 GB de espacio

En la salida ves cuántos objetos de cada tipo se borraron y cuánto espacio se recuperó.

Opciones útiles

• -f o --force: salta la petición de confirmación. Úsalo con cuidado.

docker system prune -f

• --volumes: también elimina volúmenes dangling. Por defecto no los toca.

docker system prune --volumes

• --filter "until=24h": elimina solo los recursos que no se hayan usado en las últimas 24 horas. Podés cambiar el tiempo (por ejemplo 72h o 10m).

docker system prune --filter "until=24h"

Advertencias importantes

• Si usás --volumes, se borrarán todos los volúmenes que no estén montados por ningún contenedor en ejecución. Esto incluye datos persistentes que quizá aún necesites, aunque el contenedor que los creó ya no esté activo.
• El caché de construcción se borra, lo que significa que la próxima vez que construyas una imagen Docker tendrá que volver a descargar capas y recompilar desde cero, lo que puede ralentizar el build.
• El filtro until se basa en la marca de tiempo Last Used del objeto. Si un contenedor se detuvo hace poco pero su imagen se usó hace días, la imagen podría ser eliminada si cumple el criterio, aunque todavía tengas contenedores que la referencien (en ese caso Docker la protege porque está en uso).

docker image prune: enfocado en imágenes

Cuando lo que querés liberar es específicamente espacio ocupado por imágenes, docker image prune es la opción más precisa. Trabaja únicamente con imágenes y deja intactos contenedores, volúmenes y redes.

Sintaxis básica

docker image prune

Por defecto elimina solo imágenes dangling (esas que no tienen ningún tag y no son referenciadas por ningún contenedor).

Ejemplo con salida esperada

Imaginá que tenés varias imágenes sin tag que quedaron después de hacer un docker build fallido o de actualizar un servicio.

$ docker image prune
ADVERTENCIA: Esto eliminará todas las imágenes dangling.

¿Está seguro de que desea continuar? [y/N] y

Eliminadas 5 imágenes
Liberados 1,8 GB de espacio

Opciones útiles

• -a o --all: elimina todas las imágenes que no estén siendo usadas por ningún contenedor, incluso aquellas que tienen un tag. Esta opción es más agresiva.

docker image prune -a

• --filter "until=12h": igual que en system prune, pero aplicado solo a imágenes.

docker image prune --filter "until=12h"

• -f para forzar sin confirmación.

docker image prune -af

Advertencias importantes

• Con -a podés borrar imágenes que todavía tengas en tu registro local pero que no estén en uso actualmente por ningún contenedor. Si después necesitás volver a ejecutar un contenedor basado en esa imagen, Docker la tendrá que volver a descargar del registro (o rebuild si no está ahí).
• Las imágenes que son base de otras imágenes (por ejemplo la imagen ubuntu:20.04) también pueden ser borradas si no están en uso y se especifica -a. Esto puede afectar futuros builds que dependan de esa capa.
• El filtro until se basa sugiere eliminar imágenes que no se hayan usado en el período dado. Tené en cuenta que "usado" significa que el contenedor que la usó se creó o se inició dentro de ese marco temporal. Una imagen que se usó hace 20 horas pero cuyo contenedor se detuvo hace 1 hora todavía se considera "usada recientemente" porque el contenedor existió en ese lapso.

docker volume prune: limpieza de volúmenes

Los volúmenes son la forma más segura de persistir datos en Docker, pero también pueden acumularse cuando ya no son necesarios. docker volume prune se encarga de eliminar aquellos volúmenes que no estén montados por ningún contenedor.

Sintaxis básica

docker volume prune

Al ejecutarlo, Docker lista los volúmenes dangling y pide confirmación antes de borrarlos.

Ejemplo con salida esperada

Supongamos que tenés dos volúmenes creados para pruebas que ya no están asociados a ningún contenedor.

$ docker volume prune
ADVERTENCIA: Esto eliminará todos los volúmenes locales no usados.

¿Está seguro de que desea continuar? [y/N] y

Eliminados 2 volúmenes
Liberados 450 MB de espacio

Opciones útiles

• -f o --force: salta la confirmación.

docker volume prune -f

• --filter "label=env=dev": podés filtrar por etiquetas. Sólo se borrarán los volúmenes que tengan esa etiqueta y que no estén en uso.

docker volume prune --filter "label=env=dev"

Advertencias importantes

• Este comando solo borra volúmenes dangling. Si un volumen está siendo usado por un contenedor detenido, no será eliminado. Para borrar también esos volúmenes tenés que primero eliminar el contenedor que lo referencia (con docker rm) y luego volver a ejecutar el prune.
• Los volúmenes suelen contener bases de datos, archivos de configuración o cualquier dato que necesite sobrevivir a reinicios de contenedores. Antes de ejecutar el prune, verificá que no haya volúmenes importantes sin contenedores activos (por ejemplo, un volumen de respaldo que se monta solo ocasionalmente).
• Si usás el filtro por label, asegurate de que las etiquetas estén aplicadas correctamente al crear el volumen (docker volume create --label env=dev mi_volumen).

Buenas prácticas y errores comunes

1. Hacer una inspección antes de borrar

Siempre es buena idea ver qué se va a eliminar. Docker ofrece comandos de listado que muestran los recursos dangling:

# Imágenes dangling
docker image ls -f dangling=true

# Contenedores detenidos
docker ps -f status=exited

# Redes no usadas
docker network ls

# Volúmenes dangling
docker volume ls -f dangling=true

Revisar estas listas te permite confirmar que no estás a punto de borrar algo valioso.

2. Usar filtros de tiempo con prudencia

Los filtros until y since son poderosos, pero pueden dar resultados inesperados si no entendés bien cómo Docker cuenta el "último uso".