How to Install Docker on NixOS

NixOS handles Docker differently from every other Linux distribution. There is no apt install docker-ce or dnf install docker. Everything goes through the declarative configuration system. Here is the complete guide.

Enable Docker in configuration.nix

Edit /etc/nixos/configuration.nix:

{ config, pkgs, ... }:
{
  # Enable Docker daemon
  virtualisation.docker.enable = true;

  # Add your user to the docker group
  users.users.youruser.extraGroups = [ "docker" ];
}

Apply the configuration:

sudo nixos-rebuild switch

Log out and back in for group membership to take effect, then verify:

docker --version
docker run hello-world

Docker Compose

Docker Compose is included with the Docker module in NixOS. Verify it works:

docker compose version

If you need the standalone docker-compose binary (v1 compatibility):

{
  environment.systemPackages = with pkgs; [
    docker-compose
  ];
}

Rootless Docker

For environments where you do not want to grant full Docker socket access:

{
  virtualisation.docker.rootless = {
    enable = true;
    setSocketVariable = true;
  };
}

This runs the Docker daemon under your user account. Containers cannot gain root privileges on the host, even if they escape the container namespace.

After rebuilding, rootless Docker uses a different socket:

# Rootless socket location
echo $DOCKER_HOST
# unix:///run/user/1000/docker.sock

Storage Driver Configuration

NixOS defaults to the overlay2 storage driver. If you need a different driver (for example, btrfs on a btrfs filesystem):

{
  virtualisation.docker.daemon.settings = {
    storage-driver = "btrfs";
  };
}

Other useful daemon settings:

{
  virtualisation.docker.daemon.settings = {
    storage-driver = "overlay2";
    log-driver = "json-file";
    log-opts = {
      max-size = "10m";
      max-file = "3";
    };
    default-address-pools = [
      { base = "172.17.0.0/12"; size = 24; }
    ];
  };
}

NVIDIA GPU Support

If you have an NVIDIA GPU and want Docker containers to access it:

{
  virtualisation.docker.enable = true;
  hardware.nvidia-container-toolkit.enable = true;
}

Test GPU access:

docker run --rm --gpus all nvidia/cuda:12.6-base nvidia-smi

Networking Considerations

NixOS uses its own firewall module. If Docker containers need to expose ports, ensure the NixOS firewall allows them:

{
  networking.firewall.allowedTCPPorts = [ 8080 3000 ];
  # Or disable firewall for Docker bridge (not recommended for production)
  # networking.firewall.trustedInterfaces = [ "docker0" ];
}

Temporary Docker (nix-shell)

For quick testing without enabling Docker system-wide:

nix-shell -p docker

This gives you the Docker CLI but not the daemon. You still need virtualisation.docker.enable = true for the daemon to run.

Troubleshooting

”Cannot connect to Docker daemon”

After enabling Docker, you must log out and back in for the docker group to apply:

# Check if your user is in the docker group
groups
# If docker is not listed, log out and back in

# Alternatively, use newgrp
newgrp docker

Docker service not starting

Check the service status:

sudo systemctl status docker
journalctl -u docker --no-pager -n 50

Cleaning up images and containers

# Remove all stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Nuclear option: remove everything
docker system prune -a --volumes -f

NixOS garbage collection removes Docker images

By default, nix-collect-garbage does not affect Docker. However, if you are low on disk space, Docker images may compete with the Nix store. Monitor disk usage:

docker system df
nix-store --gc --print-dead | wc -l

Related Resources

• Docker Cheat Sheet
• Podman vs Docker
• containerd vs CRI-O
• How to Install Docker on Ubuntu