How to fix OCI runtime create failed: unable to retrieve OCI runtime error: exec: "runc": executable file not found in $PATH in Docker

DockerINTERMEDIATEHIGHUpdated Dec 6, 2025· 205 views

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.

Quick fix

Fixes OCI runtime create failed: unable to retrieve OCI runtime error: exec: "runc": executable file not found in $PATH

# Check if runc exists anywhere on the system
which runc
which docker-runc

# Check runc version if found
runc --version
  1. Verify if runc is installed
  2. Install runc package
  3. Create symlinks for docker-runc compatibility
  4. Restart Docker daemon
docker — error
# Check if runc exists anywhere on the system
which runc
which docker-runc
# Check runc version if found
runc --version
OCI runtime create failed: unable to retrieve OCI runtime error: exec: "runc": executable file not found in $PATH

What this error means

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.

Typical symptoms

  • Docker run commands fail with 'OCI runtime create failed' error
  • Error message specifically mentions 'runc' executable not found in $PATH
  • Containers were working before a Docker or system upgrade
  • docker-compose up fails to start any containers
  • The error appears on custom Linux distributions or minimal installations
  • Existing containers cannot be restarted after a system update

Common causes

  1. Docker was upgraded from version 18.09+ but old container metadata references docker-runc
  2. The runc package is not installed on the system
  3. Runc binary exists but is not in a directory included in the system PATH
  4. Distribution packages Docker and runc separately and runc is missing
  5. Symlink from docker-runc to runc is missing after upgrade
  6. Containerd is configured to look for runc in a non-standard location
  7. Multiple Docker installations causing binary path conflicts

How to fix "OCI runtime create failed: unable to retrieve OCI runtime error: exec: "runc": executable file not found in $PATH"

1Verify if runc is installed

First, check whether runc is installed on your system:

bash
# Check if runc exists anywhere on the system
which runc
which docker-runc

# Check runc version if found
runc --version

If neither command returns a path, runc is not installed or not in PATH.

2Install runc package

Install runc using your distribution's package manager:

Debian/Ubuntu:

bash
sudo apt-get update
sudo apt-get install runc

RHEL/CentOS/Fedora:

bash
sudo dnf install runc
# Or on older versions:
sudo yum install runc

Arch Linux:

bash
sudo pacman -S runc

Alpine:

bash
sudo apk add runc
3Create symlinks for docker-runc compatibility

If your containers were created with an older Docker version, they may reference docker-runc instead of runc. Create symlinks to maintain compatibility:

bash
# 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-runc

For containerd-related binaries:

bash
sudo ln -s /usr/bin/containerd-shim /usr/local/bin/docker-containerd-shim
4Restart Docker daemon

After installing runc or creating symlinks, restart Docker:

bash
sudo systemctl restart docker

# Verify Docker is running
sudo systemctl status docker

# Test with a simple container
docker run --rm hello-world
5Remove and recreate problematic containers

If specific containers still fail, they may have stale runtime metadata. Remove and recreate them:

bash
# 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:

bash
docker-compose down
docker-compose up -d
6Check and update Docker daemon configuration

If runc is in a non-standard location, configure Docker to find it:

Edit /etc/docker/daemon.json:

json
{
  "runtimes": {
    "runc": {
      "path": "/path/to/your/runc"
    }
  },
  "default-runtime": "runc"
}

Then reload Docker:

bash
sudo systemctl daemon-reload
sudo systemctl restart docker
7Reinstall Docker if needed

If the issue persists, a clean Docker reinstall may be necessary:

bash
# 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 docker

Note: This will not remove your images, containers, or volumes in /var/lib/docker.

Advanced notes

### 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:

bash
sudo pacman -S docker runc containerd

OpenSUSE: Check for multiple runc versions in the repository. Install the latest:

bash
sudo zypper install runc

### Rootless Docker

If using rootless Docker, ensure runc is accessible to your user:

bash
# 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.

Frequently asked questions

What does "OCI runtime create failed: unable to retrieve OCI runtime error: exec:" mean?
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.
How do I fix "OCI runtime create failed: unable to retrieve OCI runtime error: exec:"?
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.
What causes "OCI runtime create failed: unable to retrieve OCI runtime error: exec:"?
Docker was upgraded from version 18.09+ but old container metadata references docker-runc The runc package is not installed on the system Runc binary exists but is not in a directory included in the system PATH
Is the "OCI runtime create failed: unable to retrieve OCI runtime error: exec:" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading