How to Fix Docker’s “No Space Left on Device” Error

If you’ve been working with Docker for any length of time, chances are you’ve encountered the dreaded “no space left on device” error.

This frustrating message often appears when you’re in the middle of building an image or running a container, bringing your development workflow to a screeching halt.

As a Docker user for several years, I’ve faced this issue more times than I’d like to admit. In this comprehensive guide, I’ll walk you through the causes of this error and provide several battle-tested solutions so you can get back to work quickly.

Understanding the Problem

When Docker complains about having no space left on device, it’s typically telling you one of several things:

1. The filesystem where Docker stores its data (usually /var/lib/docker) is full
2. You’ve hit an inode limit on your filesystem
3. The virtual disk image file (for Docker Desktop users) has reached its maximum size
4. Your Docker build cache has grown too large

Let’s explore how to diagnose which specific issue you’re facing and then solve it.

Read: Docker container orchestration tools

Diagnosing the Issue

Before diving into solutions, it’s important to understand what’s consuming your Docker storage. We can use Docker’s built-in tools for this:

docker system df

This command will show you a breakdown of space usage by type:

TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              22                  13                  7.581GB             3.899GB (51%)
Containers          15                  0                   2.166GB             2.166GB (100%)
Local Volumes       4                   4                   550.2MB             0B (0%)
Build Cache         611                 0                   43.83GB             43.83GB (100%)

Pay special attention to the “RECLAIMABLE” column, which shows potential space that can be freed. In this example, the build cache is consuming a massive 43.83GB of space!

For Linux users, you can also check your general disk usage and inode consumption:

df -h  # Check disk space
df -ih # Check inode usage

If your inode usage is near 100% even though you have disk space available, that’s likely your issue.

Read: How to clean up unused Docker containers, images and volumes

Solution 1: Docker System Prune (Quick Fix)

The simplest and most effective solution for most users is Docker’s built-in cleanup command:

docker system prune

This command removes:

• All stopped containers
• All networks not used by at least one container
• All dangling images (those not associated with a container)
• All dangling build cache

When you run it, Docker will show you a warning:

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all dangling images
  - all dangling build cache

Are you sure you want to continue? [y/N]

By default, this command doesn’t remove volumes. If you want to remove unused volumes as well (be careful, as this might delete data you want to keep), use:

docker system prune --volumes

For an even deeper clean that removes all unused images, not just dangling ones:

docker system prune -a --volumes

This last command is particularly powerful and will free up the most space, but will also remove all cached image layers, meaning your next docker pull or docker build operations will be slower as they’ll need to download or rebuild everything.

Read: How to remove old Docker containers

Solution 2: Targeted Cleanup

If you prefer a more surgical approach, you can clean up specific Docker components:

Cleaning Up Images

To remove dangling images (those with <none> tags):

docker images -f "dangling=true" -q | xargs docker rmi

Cleaning Up Containers

To remove all stopped containers:

docker rm $(docker ps -aq -f status=exited)

Cleaning Up Volumes

To remove unused volumes:

docker volume prune

or more specifically:

docker volume rm $(docker volume ls -qf dangling=true)

Cleaning Up the Build Cache

If your build cache is particularly large (as shown in the docker system df output earlier):

docker builder prune

This can make a huge difference, especially if you frequently build Docker images with many layers.

Solution 3: Increase Available Storage (Docker Desktop)

If you’re using Docker Desktop on macOS or Windows, you might be hitting the virtual disk size limit. Here’s how to increase it:

1. Open Docker Desktop
2. Go to Settings/Preferences > Resources > Advanced
3. Adjust the “Disk image size” slider to a larger value
4. Click “Apply & Restart”

This solution is ideal if you have plenty of disk space on your host machine and just need to allocate more to Docker.

Solution 4: Reset Docker.raw (macOS)

In some cases, especially on macOS, the Docker.raw file can grow very large despite pruning operations. This file contains the virtual disk for Docker on Mac. Here’s how to reset it:

1. Open Docker Desktop
2. Go to Preferences > Resources > Advanced > Disk Image Location
3. Note the location of the Docker.raw file (typically in /Users/[username]/Library/Containers/com.docker.docker/Data/vms/0/)
4. Quit Docker Desktop
5. Delete the Docker.raw file
6. Restart Docker Desktop

The file will be recreated automatically, starting fresh with minimal size. Be aware this will remove all containers, images, volumes, and other Docker data.

Solution 5: Change Docker’s Storage Location (Linux)

If you’re running Docker on Linux and the partition containing /var/lib/docker is too small, you can move Docker’s storage to another location with more space. Here’s how:

1. Stop the Docker daemon:

   sudo systemctl stop docker
   

2. Edit or create the Docker daemon configuration file:

   sudo vim /etc/docker/daemon.json
   

3. Add or modify the configuration to set a new data root directory:

   {
     "data-root": "/path/to/new/docker/data"
   }
   

4. Create the new directory and ensure proper permissions:

   sudo mkdir -p /path/to/new/docker/data
   sudo chown -R root:root /path/to/new/docker/data
   

5. Optionally, copy existing Docker data (if you want to preserve images, etc.):

   sudo rsync -aP /var/lib/docker/ /path/to/new/docker/data
   

6. Restart Docker:

   sudo systemctl daemon-reload
   sudo systemctl start docker
   

7. Verify the new location:

   docker info -f '{{ .DockerRootDir }}'
   

Solution 6: Check for Inode Exhaustion

Sometimes the “no space left on device” error occurs not because of running out of disk space, but because you’ve exhausted all available inodes. This is common when you have many small files, which is exactly what Docker can create with layers and small container files.

To check your inode usage:

df -ih

If you see a filesystem at or near 100% use for inodes but with available space, that’s your issue. The solution is to clean up Docker resources using the prune commands mentioned earlier.

Best Practices to Prevent Space Issues

To avoid encountering “no space left on device” errors in the future:

1. Use multi-stage builds: These result in smaller final images by discarding intermediate build stages.
2. Clean up regularly: Consider setting up a cron job to run docker system prune periodically.
3. Use the --rm flag: When running containers temporarily, use docker run --rm to automatically remove them when they exit.
4. Optimize Dockerfiles: Use fewer layers, clean up in the same layer where files are created, and avoid installing unnecessary packages.
5. Monitor Docker disk usage: Regularly check disk usage with docker system df.
6. Use smaller base images: Alpine-based images are much smaller than their Debian or Ubuntu counterparts.
7. Limit build context: Use .dockerignore files to prevent unnecessary files from being sent to the Docker daemon during builds.

One Command to Rule Them All

If you’re in a hurry and just need to free up space quickly without worrying about keeping specific resources, this “nuclear option” will clean nearly everything:

docker system prune -a -f --volumes && docker builder prune -a -f

Be careful with this command, as it removes:

• All stopped containers
• All networks not used by at least one container
• ALL images not used by a container (not just dangling ones)
• All build cache
• All volumes not used by a container

Conclusion

Docker’s “no space left on device” error can be frustrating, but with the tools and techniques outlined in this guide, you should be able to diagnose and resolve the issue quickly. Whether you choose the quick fix of docker system prune or take a more targeted approach depends on your specific needs and environment.

Remember that good Docker housekeeping habits can prevent this issue from occurring in the first place. Regular cleanup and thoughtful image design will save you from future headaches.

FAQ

Q: Will Docker system prune delete my running containers?

A: No. Docker system prune only removes stopped containers, not running ones.

Q: I ran all the prune commands but still have issues. What now?

A: Check if you’re running out of inodes rather than disk space with df -ih. Also consider resetting Docker completely or changing its storage location.

Q: How often should I run Docker system prune?

A: It depends on your usage. If you build and test many images daily, consider weekly cleanup. For lighter usage, monthly might be sufficient.

Q: Is there a way to automatically clean up Docker?

A: Yes. You can set up scheduled tasks or cron jobs to run docker system prune automatically.

Q: Will pruning affect my Docker Hub credentials or Docker Desktop settings?

A: No. Pruning only affects containers, images, networks, volumes and build cache, not your Docker configuration or credentials.

Q: Can I recover data after running docker system prune?

A: Generally no. Once pruned, the data is permanently deleted.