How to fix Error starting daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when Docker's PID file exists but the daemon isn't properly running, typically after an unclean shutdown, system crash, or when attempting to start Docker while it's already running. The fix involves removing the stale PID file and properly restarting the Docker service.

What this error means

When the Docker daemon starts, it creates a PID (Process ID) file at `/var/run/docker.pid` (or `/var/snap/docker/<version>/run/docker.pid` for snap installations). This file contains the process ID of the running Docker daemon and serves as a lock to prevent multiple daemon instances from starting simultaneously. The "pid file found, ensure docker is not running" error occurs when Docker attempts to start but finds an existing PID file. This typically happens in these scenarios: - **Unclean shutdown**: The system crashed or lost power while Docker was running, leaving a stale PID file behind - **Docker is already running**: You're trying to start Docker manually (via `dockerd`) while it's already managed by systemd or another init system - **Process terminated abnormally**: The Docker daemon crashed or was killed without proper cleanup Docker refuses to start because it interprets the existing PID file as a sign that another instance might be running. This safety mechanism prevents potential conflicts and data corruption that could occur if multiple daemon instances accessed the same containers and images.

How to fix "Error starting daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid"

1Check if Docker is actually running

Before deleting the PID file, verify whether Docker is truly running or if it's a stale file:

Check for running Docker processes:

bash

ps aux | grep -E 'dockerd|containerd'

Check systemd service status:

bash

sudo systemctl status docker
sudo systemctl status containerd

Check the PID in the file:

bash

cat /var/run/docker.pid
# Then check if that PID is actually running
ps -p $(cat /var/run/docker.pid) 2>/dev/null && echo "Process is running" || echo "Process is NOT running (stale PID)"

If the process is NOT running but the PID file exists, it's safe to remove it. If Docker IS running, you should stop it properly instead of deleting the file.

2Stop Docker service properly (if running)

If Docker processes are still running, stop them properly before proceeding:

For systemd-managed Docker:

bash

sudo systemctl stop docker
sudo systemctl stop containerd

For Docker installed via snap:

bash

sudo snap stop docker

If systemctl commands hang or fail, the daemon might be unresponsive. In that case, proceed to the next step to kill processes manually.

3Kill any remaining Docker processes

If Docker processes are still running and won't stop gracefully, kill them manually:

Find and kill Docker processes:

bash

# Find all Docker-related processes
ps -ef | grep -E 'dockerd|containerd' | grep -v grep

# Kill dockerd process
sudo pkill -9 dockerd

# Kill containerd if necessary
sudo pkill -9 containerd

# Alternatively, kill by PID from the file
sudo kill -9 $(cat /var/run/docker.pid 2>/dev/null) 2>/dev/null

Verify processes are stopped:

bash

ps aux | grep -E 'dockerd|containerd' | grep -v grep

If no processes are listed, you can proceed to clean up the PID file.

4Remove the stale PID file

Once you've confirmed Docker isn't actually running, delete the PID file:

For standard Docker installation:

bash

sudo rm -f /var/run/docker.pid

For snap-installed Docker:

bash

# Find the correct path (version number varies)
ls /var/snap/docker/*/run/docker.pid
# Remove it
sudo rm -f /var/snap/docker/*/run/docker.pid

Also check for containerd PID file:

bash

sudo rm -f /var/run/containerd/containerd.pid

Note: The PID file location may vary by distribution. Common locations:
- /var/run/docker.pid (most Linux distributions)
- /run/docker.pid (same as above, /var/run is typically symlinked to /run)
- /var/snap/docker/<version>/run/docker.pid (snap installations)

5Start Docker service

Now restart the Docker service:

For systemd-managed Docker:

bash

sudo systemctl daemon-reload
sudo systemctl start docker

For snap-installed Docker:

bash

sudo snap start docker

Verify Docker is running:

bash

sudo systemctl status docker
docker ps
docker info

You should see Docker running with no errors.

6Prevent future occurrences

To minimize the chance of this happening again:

Enable live-restore (recommended):

Add this to /etc/docker/daemon.json:

json

{
  "live-restore": true
}

This allows containers to keep running even when the daemon stops, and helps with cleaner restarts.

Ensure proper shutdown sequence:

Always stop Docker gracefully before system shutdown:

bash

sudo systemctl stop docker

For servers, configure proper shutdown order:

bash

# Docker should stop before network services
sudo systemctl add-wants shutdown.target docker.service

Monitor Docker health:

Set up monitoring to detect daemon crashes:

bash

# Create a simple watchdog script or use systemd's built-in restart
sudo systemctl edit docker.service
# Add: Restart=on-failure

Advanced notes

### Docker-in-Docker (DinD) Considerations

When running Docker inside Docker containers (common in CI/CD pipelines), the PID file issue is particularly common. The inner Docker daemon may not have a chance to clean up when the container is stopped.

Solution for DinD:

Modify your Docker entrypoint script to clean up the PID file before starting:

bash

#!/bin/sh
# run-docker.sh for DinD
rm -f /var/run/docker.pid
exec dockerd "$@"

In GitLab CI, use the official dind service image which handles this automatically:

yaml

services:
  - docker:dind

variables:
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: "/certs"

### Understanding the PID File Lock Mechanism

Docker uses the PID file as a form of inter-process communication lock:

1. On startup, dockerd checks if /var/run/docker.pid exists
2. If it exists, Docker reads the PID and checks if that process is running
3. If the process IS running, Docker refuses to start (prevents double-daemon)
4. If the process is NOT running, Docker should remove the stale file and start

However, in some edge cases (particularly after crashes), this cleanup doesn't happen properly, hence the need for manual intervention.

### Why Docker Uses PID Files

PID files serve several purposes:
- Prevent multiple instances: Only one Docker daemon should manage the container runtime
- Graceful shutdown: Init systems can read the PID to send stop signals
- Health checks: Monitoring systems can verify the daemon is running

### Snap-Specific Behavior

Docker installed via snap has a different file layout and may require additional steps:

bash

# Full cleanup for snap Docker
sudo snap stop docker
sudo rm -f /var/snap/docker/*/run/docker.pid
sudo rm -f /var/snap/docker/*/run/containerd/containerd.pid
sudo snap start docker

Check snap logs for additional errors:

bash

sudo snap logs docker -n 50

### Filesystem and Mount Issues

In some cases, the PID file cannot be deleted because:
- The filesystem is mounted read-only
- The /var/run directory is on a full disk
- SELinux or AppArmor is blocking the operation

Check filesystem status:

bash

mount | grep "run"
df -h /var/run

If read-only, remount as read-write:

bash

sudo mount -o remount,rw /var/run

### Alternative: Using Systemd Drop-in

If you frequently encounter this issue, create a systemd drop-in that cleans up before starting:

bash

sudo mkdir -p /etc/systemd/system/docker.service.d
cat << 'EOF' | sudo tee /etc/systemd/system/docker.service.d/cleanup.conf
[Service]
ExecStartPre=-/bin/rm -f /var/run/docker.pid
EOF
sudo systemctl daemon-reload

Note: The - before /bin/rm means the service will start even if the rm command fails (e.g., if the file doesn't exist).

How to fix Error starting daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid in Docker

What this error means

Typical symptoms

Common causes

How to fix "Error starting daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid"

Advanced notes

Related errors

Official resources & further reading