The 'runc not found' error occurs when Docker cannot locate the runc binary, which is the OCI-compliant container runtime that actually creates and runs containers. This typically happens after Docker upgrades or when using distribution-specific packages.
The "runc: executable file not found in $PATH" error indicates that Docker's container engine (containerd) cannot find the `runc` binary when trying to create or start a container. Runc is the low-level OCI (Open Container Initiative) runtime that performs the actual container creation - it sets up namespaces, cgroups, and executes the container process. When you run `docker run`, the request flows through several components: Docker CLI -> Docker daemon (dockerd) -> containerd -> runc. If runc is missing or not in the expected location, containerd cannot complete the container creation process, resulting in this OCI runtime error. This error frequently appears after Docker version upgrades, particularly the upgrade from Docker 18.09 which changed the binary naming convention from `docker-runc` to just `runc`. It can also occur on distributions that package Docker components separately, where the runc package may not be installed or may use a different binary path.
First, check whether runc is installed on your system:
# Check if runc exists anywhere on the system
which runc
which docker-runc
# Check runc version if found
runc --versionIf neither command returns a path, runc is not installed or not in PATH.
Install runc using your distribution's package manager:
Debian/Ubuntu:
sudo apt-get update
sudo apt-get install runcRHEL/CentOS/Fedora:
sudo dnf install runc
# Or on older versions:
sudo yum install runcArch Linux:
sudo pacman -S runcAlpine:
sudo apk add runcIf your containers were created with an older Docker version, they may reference docker-runc instead of runc. Create symlinks to maintain compatibility:
# Find where runc is installed
which runc
# Usually /usr/bin/runc or /usr/sbin/runc
# Create symlinks (adjust path if runc is elsewhere)
sudo ln -s /usr/bin/runc /usr/local/bin/docker-runc
sudo ln -s /usr/bin/runc /usr/bin/docker-runcFor containerd-related binaries:
sudo ln -s /usr/bin/containerd-shim /usr/local/bin/docker-containerd-shimAfter installing runc or creating symlinks, restart Docker:
sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status docker
# Test with a simple container
docker run --rm hello-worldIf specific containers still fail, they may have stale runtime metadata. Remove and recreate them:
# Stop and remove the container
docker stop <container_name>
docker rm <container_name>
# If that fails, remove the container state directly
sudo rm -rf /var/run/docker/runtime-runc/moby/<container_id>
# Then recreate the container
docker run ...For docker-compose projects:
docker-compose down
docker-compose up -dIf runc is in a non-standard location, configure Docker to find it:
Edit /etc/docker/daemon.json:
{
"runtimes": {
"runc": {
"path": "/path/to/your/runc"
}
},
"default-runtime": "runc"
}Then reload Docker:
sudo systemctl daemon-reload
sudo systemctl restart dockerIf the issue persists, a clean Docker reinstall may be necessary:
# Stop Docker
sudo systemctl stop docker
# Remove Docker packages (adjust for your distro)
# Debian/Ubuntu:
sudo apt-get remove docker-ce docker-ce-cli containerd.io
# Reinstall
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Start Docker
sudo systemctl start dockerNote: This will not remove your images, containers, or volumes in /var/lib/docker.
### Understanding Docker's Runtime Architecture
Docker uses a layered runtime architecture:
1. Docker CLI - User interface
2. dockerd - Docker daemon, manages containers, images, networks
3. containerd - Container runtime, manages container lifecycle
4. runc - OCI runtime, actually creates container processes
When you see "OCI runtime" errors, the problem is at the runc level.
### The docker-runc to runc Transition
Docker 18.09 (released 2018) removed the docker- prefix from binaries:
- docker-runc became runc
- docker-containerd became containerd
- docker-containerd-shim became containerd-shim
Containers created before this change store the old binary names in their metadata. When Docker tries to use these containers with the new binary names, it fails to find them.
### Distribution-Specific Considerations
Red Hat/CentOS: The official Docker packages work well, but packages from EPEL or other repos may have path differences.
Arch Linux: Docker and runc are separate packages. Both must be installed:
sudo pacman -S docker runc containerdOpenSUSE: Check for multiple runc versions in the repository. Install the latest:
sudo zypper install runc### Rootless Docker
If using rootless Docker, ensure runc is accessible to your user:
# Check runc is in user PATH
echo $PATH
which runc
# If not, add to ~/.bashrc:
export PATH=$PATH:/usr/bin### Kubernetes and Container Runtimes
If running Kubernetes, the kubelet also needs access to runc. Ensure the binary is available to the kubelet process and any containerd configuration points to the correct path.
unable to configure the Docker daemon with file /etc/docker/daemon.json
How to fix 'unable to configure the Docker daemon with file daemon.json' in Docker
docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory
How to fix 'exec: entrypoint.sh: no such file or directory' in Docker
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker