Why Does ENTRYPOINT Fail to Pass Runtime Python Commands Like CMD in Docker?

A Docker container runs a single process. Docker assembles its command line by concatenating the ENTRYPOINT and CMD into a single list.

When you docker run an-image command and args, it acts as though you ran CMD ["command", "and", "args"], possibly overriding the CMD from the Dockerfile. This is appended to the image's ENTRYPOINT and becomes the main container command.

In your first example, where you set CMD ["bash", "-l", "-c"], the command-line python --version replaces this CMD and it works fine. If you set it as the ENTRYPOINT, though, it's appended to it. That would make the main container command

BASHCopied
bash -l -c python --version

Now you run into a syntactic quirk of sh -c: it takes the single next argument and runs it as a command, and any remaining arguments are assigned to the positional parameters $0, $1, .... This syntax runs python with no arguments, and with $0=--version. That's not what you want.

As a useful side note, you can use this syntax to inject any command you want in most images. For example,

BASHCopied
# DEBUG: check the Python version
docker run --rm my-image python --version

# DEBUG: check that files got installed correctly
docker run --rm my-image ls ./main_package

# DEBUG: interactive shell
docker run --rm -it my-image bash

# Run a Celery worker, assuming that's installed
docker run -d --name worker my-image celery worker ...

So how should you set ENTRYPOINT and CMD?

A best case here is to use the Python entry points system to create a command-line wrapper for your tool. Then you can pip install it (into the image's "system" Python) and a wrapper that runs the application with the standard Python version will be in $PATH. Set that wrapper as CMD.

DOCKERFILECopied
FROM python:3.12
WORKDIR /app
COPY ./ ./
RUN pip install .
CMD ["myapp"]  # from pyproject.toml [project.scripts]

If that approach doesn't work and you need to run the script directly, make sure its first line is a "shebang" line #!/usr/bin/env python3, and that it's executable (run chmod +x myapp.py on the host; source-control systems will preserve this setting). Then you can directly run ./myapp.py without naming an interpreter.

DOCKERFILECopied
FROM python:3.12
WORKDIR /app
COPY ./ ./
RUN pip install --deps-only .
CMD ["./myapp.py"]

If you really must name the interpreter explicitly, then include it directly in the CMD.

DOCKERFILECopied
CMD ["python3", "./myapp.py"]

I tend to prefer CMD since running alternate commands is frequently a useful thing to do, and managing lists of command-line arguments can get tricky (my code accepts environment-variable settings and my container setups prefer these). It's a reasonable and common pattern to use ENTRYPOINT instead of CMD in any of the above. If you did, then you would not be able to override the command as easily as above, but docker run image-name --option would pass the options to the script in a way argparse would be able to see.

I'd avoid a couple of things shown in this question:

• Do not put the interpreter in ENTRYPOINT and the script name in CMD. This means that you still need to repeat the script name if you need to provide arguments, but you can't run anything that's not a Python script. If you need to explicitly say python, put them together in the same ENTRYPOINT or CMD list.
• Do not set ENTRYPOINT ["sh", "-c"]. It would force an unusual syntax of putting the entire command in a single shell word. If you think you need this, leave out ENTRYPOINT entirely.
• Do not set ENTRYPOINT or CMD to bash or a dummy sleep command "to keep the container alive". Instead, docker run --rm -it image-name bash to get a temporary container overriding the image's CMD with a debugging shell.

The issue is with how CMD and ENTRYPOINT work together. Your CMD isn't working because it is trying to run bash with no arguments, rather than setting up python as the base command.​​​​​​​​​​​​​​​​ Here's how I’ll fix this:

DOCKERFILECopied
FROM python:3.11-slim

ENTRYPOINT ["python"]

The difference is:

• CMD gives a default command that can be completely replaced
• ENTRYPOINT sets the base command that docker run arguments get added to

So with ENTRYPOINT ["python"]:

• docker run image --version becomes python --version
• docker run image script.py becomes python script.py

Also, this blogpost breaks these concepts down pretty well. https://www.docker.com/blog/docker-best-practices-choosing-between-run-cmd-and-entrypoint/