How to fix cannot find /usr/bin/python: No such file or directory in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 240 views

This error occurs when a Docker container tries to execute a script or command that requires Python, but the Python interpreter is not installed or is at a different path in the container's filesystem.

Quick fix

Fixes cannot find /usr/bin/python: No such file or directory

# View the shebang line of your script
head -1 your_script.py

# Common shebangs:
#!/usr/bin/python      # Usually expects Python 2
#!/usr/bin/python3     # Explicitly Python 3
#!/usr/bin/env python  # Uses PATH to find python
#!/usr/bin/env python3 # Uses PATH to find python3
  1. Identify which Python version you need
  2. Install Python in your Dockerfile
  3. Use a Python base image instead
  4. Update shebang lines in scripts
docker — error
# View the shebang line of your script
head -1 your_script.py
# Common shebangs:
#!/usr/bin/python      # Usually expects Python 2
#!/usr/bin/python3     # Explicitly Python 3
#!/usr/bin/env python  # Uses PATH to find python
#!/usr/bin/env python3 # Uses PATH to find python3
cannot find /usr/bin/python: No such file or directory

What this error means

The error "cannot find /usr/bin/python: No such file or directory" indicates that the container is trying to run a script or command that expects Python to be available at /usr/bin/python, but no Python executable exists at that location. This is a common issue because the specific path /usr/bin/python typically refers to Python 2, which is no longer included by default in most modern Linux distributions and Docker base images. This error can occur in several scenarios: when running a script with a shebang line pointing to /usr/bin/python, when a build tool or package manager expects Python at that location, or when using a minimal base image (like Alpine or slim variants) that doesn't include Python at all. The root cause is usually a mismatch between what the script or application expects and what's actually available in the container. Modern systems typically only have Python 3 installed, and it's usually available as python3 or /usr/bin/python3 rather than the unversioned python command.

Typical symptoms

  • Container fails to start with 'cannot find /usr/bin/python' error
  • Scripts fail with 'bad interpreter: No such file or directory'
  • Build process fails when running Python-dependent tools
  • Error appears when running scripts with #!/usr/bin/python shebang
  • npm install or other package managers fail looking for Python
  • Container starts but crashes immediately when trying to run Python scripts

Common causes

  1. Base image does not include Python (common with Alpine, slim, or scratch images)
  2. Script uses shebang #!/usr/bin/python but only Python 3 is installed as /usr/bin/python3
  3. Python 2 was expected but is not installed (Python 2 reached end-of-life)
  4. Multi-stage build didn't copy Python interpreter to final image
  5. Using a minimal base image that excludes Python to reduce size
  6. Symlink from python to python3 doesn't exist in the container
  7. PATH environment variable doesn't include the directory containing Python
  8. Node.js native modules requiring Python for compilation (node-gyp)

How to fix "cannot find /usr/bin/python: No such file or directory"

1Identify which Python version you need

First, determine if your application needs Python 2 or Python 3. Check your scripts' shebang lines and any documentation:

bash
# View the shebang line of your script
head -1 your_script.py

# Common shebangs:
#!/usr/bin/python      # Usually expects Python 2
#!/usr/bin/python3     # Explicitly Python 3
#!/usr/bin/env python  # Uses PATH to find python
#!/usr/bin/env python3 # Uses PATH to find python3

Most modern applications should use Python 3, as Python 2 reached end-of-life in January 2020.

2Install Python in your Dockerfile

Add Python installation to your Dockerfile using the appropriate package manager for your base image:

dockerfile
# For Debian/Ubuntu-based images
RUN apt-get update && apt-get install -y python3 python3-pip && \
    ln -s /usr/bin/python3 /usr/bin/python && \
    rm -rf /var/lib/apt/lists/*

# For Alpine-based images
RUN apk add --no-cache python3 py3-pip && \
    ln -s /usr/bin/python3 /usr/bin/python

# For RHEL/CentOS/Fedora-based images
RUN dnf install -y python3 python3-pip && \
    ln -s /usr/bin/python3 /usr/bin/python

The symlink command creates the /usr/bin/python alias pointing to python3.

3Use a Python base image instead

If your application heavily relies on Python, consider using an official Python base image:

dockerfile
# Full Python image
FROM python:3.12

# Slim variant (smaller, but has Python)
FROM python:3.12-slim

# Alpine variant (smallest, uses musl libc)
FROM python:3.12-alpine

# Your application code
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

This ensures Python is properly installed and configured with all necessary tools.

4Update shebang lines in scripts

If you control the scripts, update the shebang to use python3 explicitly or use env for portability:

bash
# Change from:
#!/usr/bin/python

# To one of these:
#!/usr/bin/python3
#!/usr/bin/env python3

You can update shebangs in your Dockerfile:

dockerfile
# Fix shebang in existing scripts
RUN sed -i 's|#!/usr/bin/python|#!/usr/bin/python3|g' /app/script.py

Using #!/usr/bin/env python3 is more portable as it finds python3 in the PATH.

5Handle node-gyp Python requirements

If the error occurs during npm install (node-gyp needs Python), configure the Python path:

dockerfile
# Install Python and set it for node-gyp
RUN apt-get update && apt-get install -y python3 make g++ && \
    rm -rf /var/lib/apt/lists/*

# Tell npm/node-gyp where Python is
ENV PYTHON=/usr/bin/python3

# Or configure npm directly
RUN npm config set python /usr/bin/python3

# Then run npm install
RUN npm install

For newer Node.js versions, you may also need build-essential or equivalent build tools.

6Debug by inspecting the container

If you're unsure what Python is available, inspect the container:

bash
# Run an interactive shell in the container
docker run -it --entrypoint /bin/sh <image_name>

# Check if Python exists and where
which python
which python3
ls -la /usr/bin/python*

# Check PATH
echo $PATH

# Test Python directly
python3 --version

This helps identify exactly what's available and what's missing.

7Use alternatives for minimal images

For multi-stage builds or minimal images where you don't want full Python:

dockerfile
# Multi-stage build example
FROM python:3.12 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD ["python", "app.py"]

This keeps the final image smaller while ensuring Python is available.

Advanced notes

Python 2 vs Python 3 in containers: The unversioned python command historically referred to Python 2. Since Python 2's end-of-life in 2020, most distributions no longer include it. If you absolutely need Python 2 for legacy code, you'll need to install it explicitly, but be aware that Python 2 packages are increasingly unavailable in modern package repositories.

Alpine Linux considerations: Alpine uses musl libc instead of glibc. Some Python packages with C extensions may not work or may need additional build dependencies. Consider using python:3.12-slim instead of python:3.12-alpine if you encounter compatibility issues.

The python-is-python3 package: On Debian/Ubuntu-based images, you can install the python-is-python3 package which creates the necessary symlinks:

dockerfile
RUN apt-get update && apt-get install -y python-is-python3

PEP 394 compliance: According to PEP 394, the python command should not be expected to exist on systems. Scripts should use python3 explicitly. Update legacy scripts to follow this standard for better compatibility.

Distroless and scratch images: These ultra-minimal images contain no package manager or shell. If you need Python, you must use multi-stage builds to copy the Python installation, which is complex. Consider using gcr.io/distroless/python3 instead.

Frequently asked questions

What does "cannot find /usr/bin/python: No such file or directory" mean?
The error "cannot find /usr/bin/python: No such file or directory" indicates that the container is trying to run a script or command that expects Python to be available at /usr/bin/python, but no Python executable exists at that location. This is a common issue because the specific path /usr/bin/python typically refers to Python 2, which is no longer included by default in most modern Linux distributions and Docker base images. This error can occur in several scenarios: when running a script with a shebang line pointing to /usr/bin/python, when a build tool or package manager expects Python at that location, or when using a minimal base image (like Alpine or slim variants) that doesn't include Python at all.
How do I fix "cannot find /usr/bin/python: No such file or directory"?
This error occurs when a Docker container tries to execute a script or command that requires Python, but the Python interpreter is not installed or is at a different path in the container's filesystem.
What causes "cannot find /usr/bin/python: No such file or directory"?
Base image does not include Python (common with Alpine, slim, or scratch images) Script uses shebang #!/usr/bin/python but only Python 3 is installed as /usr/bin/python3 Python 2 was expected but is not installed (Python 2 reached end-of-life)
Is the "cannot find /usr/bin/python: No such file or directory" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading