TutorialKart.comIn this Docker tutorial, we learn how to build a Docker image with a Python application. We use a small Python script, create a Dockerfile, build the image, run the container, check the local image list, and save the Docker image as a tar file for use on another computer.
Docker Image with Python Application: What This Example Covers
This example is useful when you want to package a Python program with its runtime so that it can run in the same way on another machine with Docker installed. The tutorial keeps the application simple, but the same workflow applies to larger Python projects that include modules, requirements files, or web frameworks.
- Create a separate project directory for the Python Docker example.
- Add a Python file that prints a message.
- Create a Dockerfile that copies the application into an image.
- Build and run the Docker image locally.
- Save the Docker image to a tar file for transfer.
Build Docker Image with Python Application Step by Step
Before you start, make sure Docker is installed and running. You can confirm this from a terminal by running the Docker version command.
docker --versionThe commands below should be run from the directory that contains the Python file and the Dockerfile, unless a command explicitly uses another path.
1 Create a Docker project directory for the Python app
A separate directory is useful to organise docker applications. For this Python Example, create a directory somewhere with name of your choice. We shall use the name python-application
You can create and enter the directory from a terminal as shown below.
mkdir python-application
cd python-application2 Create the Python application file for Docker
Create a simple Python File, in the directory python-application, with name PythonExample.py containing the following content :
print("HelloWorld from Python Applicaiton in Docker")Reference – Python Tutorial.
At this point, your project directory contains one Python file. The Docker image will later copy this file into the image and run it with Python.
3 Create Dockerfile for the Python application image
Create a file with name Dockerfile. Dockerfile contains instructions to prepare Docker image with our Python Application.
Following is the content of Dockerfile.
FROM python
COPY . /src
CMD ["python", "/src/PythonExample.py"]This Dockerfile uses the official Python image as the base image, copies the current directory into /src inside the image, and runs PythonExample.py when a container starts from the image.
For a small learning example, this Dockerfile is enough. In real projects, it is better to use a specific Python version tag instead of a moving tag such as latest, because a fixed tag makes builds more predictable.
FROM python:3.12-slim
WORKDIR /src
COPY PythonExample.py .
CMD ["python", "PythonExample.py"]If your Python project has temporary files, virtual environments, cache folders, or local test output, add a .dockerignore file so those files are not sent to the Docker build context.
__pycache__/
*.pyc
.venv/
venv/
.env
.git/4 Build Docker image from the Python application directory
Run the following command in Terminal, from python-application directory, to create Docker Image with Python Application.
$ docker build -t python-application .root@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application# docker build -t python-application .
Sending build context to Docker daemon 3.072kB
Step 1/3 : FROM python
latest: Pulling from library/python
aa18ad1a0d33: Pull complete
15a33158a136: Pull complete
f67323742a64: Pull complete
c4b45e832c38: Pull complete
b71152c33fd2: Pull complete
d8eff2a5d585: Pull complete
f80b3bd3dbda: Pull complete
e5b3e7f65920: Pull complete
Digest: sha256:2cbebfb9309a8b7b31c2fea8813436e297855f91cedd9cc28582678da905e5e0
Status: Downloaded newer image for python:latest
---> 26acbad26a2c
Step 2/3 : COPY . /src
---> 702fd061cbd3
Removing intermediate container f9a28d25df1e
Step 3/3 : CMD python /src/index.py
---> Running in 4e9ad3906a79
---> 71deae3e7961
Removing intermediate container 4e9ad3906a79
Successfully built 71deae3e7961
Successfully tagged python-application:latest
root@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application#Docker image with python application is created successfully.
The image name is set with -t python-application. The final dot . tells Docker to use the current directory as the build context. If your Dockerfile is in a different directory, run the command from that directory or pass the correct path.
5 Check the Docker image created for the Python app
To display available docker images, run the following command.
$ docker imagesroot@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
python-application latest 71deae3e7961 41 minutes ago 690MB
<none> <none> ce17e2d430ef 29 hours ago 643MB
python latest 26acbad26a2c 4 days ago 690MB
java 8 d23bdf5b1b1b 8 months ago 643MB
hello-world latest c54a2cc56cbb 14 months ago 1.85kB
docker/whalesay latest 6b362a9f73eb 2 years ago 247MB
root@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application#The image list shows the repository name, tag, image ID, creation time, and size. In this example, the image is available locally as python-application:latest.
6. Run Docker image with the Python application
Run the image to start a container. The container executes the command from the Dockerfile and then exits because this Python program only prints one line.
root@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application# docker run python-application
HelloWorld from Python Applicaiton in Docker
root@arjun-VPCEH26EN:/home/arjun/workspace/docker/python-application#
For scripts that read arguments, you can pass arguments after the image name. For long-running Python applications, such as web apps, you would also expose and publish ports.
docker run --rm python-applicationThe --rm option removes the stopped container automatically after the Python script finishes. This keeps your local Docker environment cleaner while testing small scripts.
7. Save Docker image with Python application to a tar file
Save the Docker Image file to a tar file, so that the image file could be copied to other machines through disk storage devices like pen-drive, etc.
Run the following command to save Docker image as a tar file.
$ docker save -o /home/arjun/workspace/docker/python-application.tar python-applicationSaving might take few seconds. Wait for the command to complete.
root@arjun-VPCEH26EN:/home/arjun/workspace/docker# ls
java-application python-application python-application.tar
root@arjun-VPCEH26EN:/home/arjun/workspace/docker# Now you may copy or ship the Docker Image file that is having Python Application.
On another computer where Docker is installed, load the saved image from the tar file and run it using the same image name.
docker load -i python-application.tar
docker run --rm python-applicationDockerfile Line-by-Line Explanation for This Python Image
The Dockerfile in this tutorial has three main instructions. Understanding them helps you modify the example for your own Python files.
| Dockerfile instruction | Purpose in this Python example |
|---|---|
FROM python | Starts from an image that already includes Python. For repeatable builds, prefer a specific tag such as python:3.12-slim in new projects. |
COPY . /src | Copies the files from your current project directory into the /src directory inside the image. |
CMD ["python", "/src/PythonExample.py"] | Sets the default command that runs when a container is started from the image. |
If you later add dependencies, create a requirements.txt file and install it in the Dockerfile before copying the full source code. That approach can improve Docker layer caching for larger Python projects.
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "PythonExample.py"]Common Docker Python Image Problems and Fixes
| Problem | Likely reason | Fix |
|---|---|---|
python: can't open file | The file path in CMD does not match the copied file location. | Check the filename, case, and path. In this tutorial, the file is /src/PythonExample.py. |
docker build cannot find Dockerfile | The command is not being run from the directory that contains Dockerfile. | Run the build command from python-application, or pass the Dockerfile path with -f. |
| The Docker image is larger than expected | The base image may include tools not needed by the app, or the build context may include local files. | Use a slimmer Python tag for new projects and add a .dockerignore file. |
| Changes in Python code do not appear | The image was not rebuilt after editing the source file. | Run docker build -t python-application . again before running the image. |
Docker Python Application Example FAQs
Should I use python or a specific Python image tag in Dockerfile?
For a quick learning example, FROM python works. For real projects, use a specific tag such as python:3.12-slim so that the Python version and base image are more predictable across builds.
Why does the Python Docker container stop immediately after running?
The container stops because the Python script finishes after printing one line. A container runs only while its main process is running. Web servers, workers, and other long-running Python programs keep the container active until the main process exits.
How do I add Python packages to this Docker image?
Add a requirements.txt file and install it with pip in the Dockerfile. For example, copy requirements.txt, run pip install --no-cache-dir -r requirements.txt, and then copy the rest of the application files.
What is the difference between docker save and docker export for a Python app?
docker save saves an image with its tags and layers, which is suitable when you want to move the built Python image to another machine. docker export exports a container filesystem and is not the usual choice for transferring a reusable image.
Do I need Docker Compose for this simple Python image?
No. Docker Compose is not required for this single-script example. Compose becomes useful when the Python application must run with other services, such as a database, cache, queue, or multiple containers.
Editorial QA Checklist for This Docker Python Tutorial
- The Python filename in the Dockerfile matches
PythonExample.py. - The build command is run from the directory that contains
Dockerfile. - New command examples use
language-bash, and existing historical terminal examples are kept unchanged. - The tutorial explains both the original learning Dockerfile and the safer fixed-version Dockerfile pattern.
- The save-and-load workflow uses
docker savefor the image anddocker loadon the target machine.
Summary: Build, Run, and Save a Docker Image for Python
In this Docker Tutorial – Docker Python Application Example, we have learnt to build a Docker Image with Python Application and also how to save the image to a file and transfer it to other computers or servers. The key workflow is to place the Python file and Dockerfile in one project directory, build the image with docker build, run it with docker run, and save it with docker save when you need to move the image offline.