Home
Blog
Data Science
How to Run a Docker Python Script? A Complete Guide

How to Run a Docker Python Script? A Complete Guide

Q: 1. Why is my Python script running slower inside Docker than locally?

Slower performance is often caused by inefficient Dockerfile configurations, such as unoptimized layers or excessive dependencies. Consider using a smaller base image, limiting the use of volume mounts, or profiling the container’s I/O performance. Additionally, ensure you’re not overloading the container with unnecessary system services that may consume resources.

Q: 2. How do I debug Python errors inside a Docker container?

To debug inside a container, use docker exec -it <container_id> bash to get access to the container’s shell. From there, you can run your script manually or use Python’s built-in debugger, pdb. If you prefer logging, set up logging to output to stdout or mount logs to a local directory for easier inspection.

Q: 4. Ensure you’re setting the environment variables correctly when running the container. Use docker run -e VAR=value to pass variables or use --env-file for multiple variables. Inside Python, prefer u

Yes, but it requires additional setup. Use nvidia-docker or Docker’s --gpus all option to enable GPU support. You’ll need a base image that includes GPU drivers like CUDA, and make sure your host machine has the appropriate NVIDIA drivers installed to make the container aware of the GPU.

Q: 5. How do I reduce Docker image size when using Python packages?

You can reduce image size by using multi-stage builds. In the first stage, use a full Python image to install dependencies, then copy over only the necessary parts to a smaller image like python:3.9-alpine. This avoids unnecessary build tools and libraries from bloating the final container.

Q: 6. Why does pip install keep reinstalling packages every time I build the image?

The issue usually arises because your COPY command is placed before the RUN pip install command in your Dockerfile. Docker rebuilds the entire layer when any file changes. To solve this, install dependencies first, and then copy the rest of your code, allowing Docker to cache the dependency installation layer.

Q: 7. How do I pass arguments to my Python script inside Docker?

You can pass arguments to your script using the CMD or ENTRYPOINT in your Dockerfile. For example, use CMD ["python", "script.py", "arg1", "arg2"] or pass them dynamically at runtime with docker run <image> arg1 arg2. Inside your Python script, retrieve the arguments using sys.argv.

Q: 8. What’s the best way to persist output data generated by a script inside Docker?

Use Docker volumes or bind mounts to persist data. Bind mounts let you map a local directory to a container path, ensuring the data is stored outside the container. For example, use docker run -v $(pwd)/data:/app/output to persist output data in a local data folder, preventing data loss when the container stops.

Q: 9. How can I ensure my Python script auto-restarts if the container crashes?

Docker offers a --restart policy, such as --restart=on-failure or always, which automatically restarts the container when it stops unexpectedly. This is ideal for background jobs or long-running scripts. Alternatively, use tools like Docker Compose to define health checks and ensure the container restarts based on your criteria.

Q: 10. Why does my script behave differently when using docker run vs docker-compose?

The discrepancies often arise due to different environment configurations between docker run and docker-compose. docker-compose.yml files can override volumes, environment variables, and entrypoints that aren't properly set in the docker run command. Review both configurations to ensure they align, especially for volumes and environment setups.

By Rohit Sharma

Updated on Apr 28, 2025 | 14 min read | 1.4k views

Table of Contents

Did you know? Over 70% of Fortune 100 companies, including top tech firms, banks, and retailers, use Docker to streamline their development and deployment processes. This widespread adoption underscores Docker's pivotal role in modernizing infrastructure and accelerating application delivery across industries.

Learning to containerize Python scripts with Docker ensures consistent execution across environments. For example, a data science team working on a machine learning model may face issues with differing Python versions or missing dependencies.

Containerizing the application means bundling everything needed to run the model together. It will work the same on every machine and server, streamlining development and deployment while minimizing errors.

This guide will help you understand how Docker works with Python and how to set up your Python Dockerfile. You’ll also learn how to run your Docker Python scripts in containers for a smooth, reproducible development experience.

Step-by-Step Setup to Run Python in Docker

Running Python in Docker removes environment drift by locking your code, interpreter, and system libraries into a container that runs identically everywhere.

Think of Docker as a container that bundles your Python script along with everything it needs: Python version, libraries, environment variables, system dependencies. Docker is ideal for running batch data processing jobs in Python, testing APIs in isolated environments, and deploying Python-powered microservices with minimal setup

Teams use this setup to automate ETL jobs, test APIs, and ship microservices without worrying about version conflicts or broken installs. What follows is a ground-up setup built for real use.

Here's how to set it up from scratch:

Step 1: Prepare Your Python Script and Project Files

Before diving into Docker, start with a simple Python script. For example, let's take the following script:

# app.py
import sys
name = sys.argv[1] if len(sys.argv) > 1 else "world"
print(f"Hello, {name}!")

Now, organize your project by creating a clean folder structure:

/docker-python-app
 ├── app.py
 └── Dockerfile  ← (we'll write this next)

Why It Matters: Keeping your project files organized is essential for Docker. The Dockerfile is critical because it defines how your app will run inside a container. Docker copies everything from the folder (called the build context), so ensuring your project directory is clean helps avoid bloated images and unnecessary dependencies.

For instance, placing only the essential files like app.py and Dockerfile in the root folder ensures Docker builds an efficient container, preventing unexpected bugs that can arise from extraneous files.

Additionally, keeping the Dockerfile separate from your app script makes it easier to maintain, especially when your project grows. It defines how your Python environment will be set up, which is crucial for Docker to containerize your script efficiently.

Step 2: Install Docker and Set It Up

To get started with Docker, first, you'll need to install it from the official Docker site.

For macOS or Windows, download and install Docker Desktop.
For Linux, you can install Docker through your package manager. Make sure to follow the installation instructions specific to your distribution (e.g., apt-get for Ubuntu, yum for CentOS, etc.).

Once installed, open your terminal and run the following command to check if Docker is installed correctly:

docker --version

If you see something like Docker version 24.0.5, you’re all set.

Tip for Linux Users: To avoid having to type sudo before every Docker command, add your user to the Docker group. This will streamline your workflow by allowing you to run Docker commands without elevated privileges. Here's how to do it:

sudo usermod -aG docker $USER

After this, log out and log back in for the changes to take effect.

Also Read: Python Cheat Sheet: From Fundamentals to Advanced Concepts for 2025

Step 3: Write Your Dockerfile

Here’s a clean, minimal Dockerfile.

# Use an official Python base image
FROM python:3.10-slim
# Set working directory inside the container
WORKDIR /app
# Copy local code to container
COPY app.py .
# Set default command
CMD ["python", "app.py"]

The WORKDIR line ensures that the working directory is set inside the container. This is useful for consistency when dealing with relative paths. The CMD command tells Docker to run the script upon starting the container

Why it works:

slim keeps image size low
WORKDIR keeps paths consistent
CMD ensures Python runs on container start

Want to learn how to use Docker Python scripts? Join upGrad’s Online Software Development Courses and work on hands-on projects that simulate real industry scenarios. With a focus on trending programming languages and the latest technologies, you’ll be equipped for success in your career.

Step 4: Build Your Docker Image

Now let’s turn everything into a Docker image.

docker build -t docker-python-demo .

Expected output:

Step 1/5 : FROM python:3.10-slim
---> sha256:...
Step 2/5 : WORKDIR /app
---> Using cache
...
Successfully tagged docker-python-demo:latest

When you run docker build, Docker reads the Dockerfile to create an image. Each line in the Dockerfile represents a layer in the image, and Docker caches each layer for efficiency. Once built, the image is ready to be used to run containers.

Pro Tip: Tagging your image with a version number, such as docker-python-demo:v1, helps manage different versions of your application, especially in team environments or production deployments.

Step 5: Run the Docker Container

You’re ready to run the script. Here’s how to do it:

docker run docker-python-demo

The docker run command creates a container from your image and starts it. You can also pass arguments as if you were running the script locally. For example, docker run docker-python-demo Alice runs the script with Alice as an argument instead of the default 'world'.

Output:

Hello, world!

You can also pass arguments:

docker run docker-python-demo Arjun

Output:

Hello, Arjun!

This behavior mirrors how you'd run the script locally with python app.py Alice, but it's now inside a fully isolated container.

Optional: Pass Arguments or Mount Volumes

Make your Docker container more flexible by passing dynamic arguments or mounting volumes, allowing you to customize runtime behavior. For example, when running a Python ETL script, you might want to mount a local directory containing configuration files or data that your script needs to process.

Passing arguments:

docker run docker-python-demo Bob

Mounting a local folder: Let’s say you want your script to read a file from your machine.

docker run -v $(pwd):/app docker-python-demo

This mounts your current folder into /app in the container. This is perfect for configs, logs, or data files.

Many DevOps teams now use Dockerized Python scripts for:

ETL jobs
API testing
Scheduled cron-like tasks
Lightweight backend services
Data pipeline components

It’s not just about convenience, it’s about reliability at scale. Want to take it further? You can link your Docker Python script to a PostgreSQL container, expose it via Flask, or orchestrate it with Kubernetes. But it all starts with one containerized .py file (Python Dockerfile) that just works.

Companies like Spotify and Netflix use containerized Python scripts for:

Batch jobs
Automated ETL pipelines
Microservices
Infrastructure scripting

And it's not just big tech. Docker is the top-used tool amongst developers (53%).

Pairing your expertise in Python and Docker with a certification from one of upGrad’s DBA programs from world-class B-Schools can help you move into C-Suite roles in technology. Along with earning a doctorate, you’ll publish original research and collaborate with industry leaders.

Also Read: Essential Skills and a Step-by-Step Guide to Becoming a Python Developer

Next, let's explore the drawbacks of running a Python Script in Docker and their workarounds.

Liverpool John Moores University

MS in Data Science

Dual Credentials

Master's Degree17 Months

IIIT Bangalore

Post Graduate Certificate in Data Science & AI (Executive)

Placement Assistance

Certification6 Months

Challenges of Running Python in Docker and How to Solve Them?

Even when a Docker container runs successfully, the behavior of Python within it often diverges from expectations. Silent failures, inconsistent permissions, and sluggish builds can occur due to misconfigured environments, improper volume mounts, or overlooked dependency mismatches.

These issues rarely surface with clear errors, making debugging non-trivial and time-consuming. Understanding the underlying Docker layers and how Python interacts with them is crucial for achieving consistent and predictable performance.

Challenge	Why It Happens	How to Solve It
Bloated image size	Your image is 700MB+ even for a small script. Usually caused by using full Python images or copying the entire directory without filters.	Use python:3.X-slim, add a .dockerignore file, and delete build artifacts with rm after installing.
Package install failures	pip install psycopg2 or lxml fails with compile errors. These packages need system-level headers that aren't in the base image.	Add dependencies like libpq-dev, gcc, or build-essential in the Python Dockerfile before pip installs.
Locale or timezone errors	Errors like locale.Error: unsupported locale setting show up, especially when formatting dates or reading encodings. Happens because the base image lacks your expected locale.	Install locales and add ENV LC_ALL=C.UTF-8 and LANG=C.UTF-8 in the Dockerfile.
Container exits too soon	You run the container, and it just stops. That’s expected—Docker runs your script and exits. But it feels broken if you expected logs or a long process.	Use docker logs, or run with --detach to keep it alive. For scripts with continuous tasks, loop or schedule inside the code.
Files owned by root	Your output files on the host can’t be opened or edited. Happens because the container runs as root by default.	Add a non-root user inside the Python Dockerfile using RUN useradd, and switch with USER before running the script.
Volumes don’t sync (especially on Windows)	Mounted folders appear empty or cause permission errors. Usually happens due to incorrect paths or OS-level mount issues.	Use double-slash paths like //c/Users/..., and ensure Docker Desktop has volume access permissions set for your drive.
Wrong Python version behavior	Your script crashes with version-specific syntax errors. You used a base image like python:latest, which may differ from your local dev version.	Pin your base image (python:3.10.9), and align local environments using pyenv or asdf version managers.
Can't debug inside the container	You need to poke around, but there's no shell access or logs aren't showing. Containers default to running commands with no TTY.	Use -it flags and override the CMD with /bin/bash or /bin/sh to get a shell inside.
Cron or background jobs silently fail	You schedule something in cron, but it never runs. Docker doesn’t start init systems by default, so cron doesn’t get triggered.	Use supervisord, or run cron manually via CMD. Alternatively, schedule tasks externally and call the container as needed.
Stale or broken dependency installs	You changed requirements.txt, but Docker caches the old layer and doesn’t rebuild pip installs.	Copy requirements.txt first, install with --no-cache-dir, and force rebuilds with --no-cache on build.
Missing environment variables	You get KeyError when accessing config vars. Happens when you forget to pass in environment variables at runtime.	Use -e VAR=value, load from a .env file, or bake them into the image with ENV if safe.

These issues tend to show up when you run a batch job in CI, deploy on ECS, or mount volumes across machines. Solving them upfront can save you hours of troubleshooting later.

You can enhance your knowledge with practical applications of Docker Python scripting with upGrad’s Learn Basic Python Programming. It covers fundamental coding concepts, including conditional statements, looping syntax, and operators in Python.

Also Read: 50 Python Project Ideas With Source Code [2025 Guide]

Next, let’s look at some best practices that can help you avoid the common challenges in Docker Python scripting.

Practical Use Case Scenarios of Docker Python Script

Some Python scripts look harmless until they need to survive CI, scale across teammates, or deploy to production. What breaks them isn’t bad code but invisible differences like OS quirks, dependency drift, or subtle version mismatches. Docker gives you a clean slate every time, turning that fragile script into an isolated, production-ready unit.

Let’s break down where it matters most.

1. Data Science Projects That Break When Re-run

Ever trained a model that worked once, then failed a week later? Version mismatches are brutal in data science. Pystan, tensorflow, prophet all rely on system libraries that change over time.

For example, in a data science project, Docker can be used to ensure that the Python environment (including libraries like pandas, numpy, scikit-learn) is identical across local machines, cloud environments, and production systems, preventing compatibility issues.

Dockerfile:

FROM python:3.9-slim
RUN apt-get update && apt-get install -y build-essential
RUN pip install prophet
COPY train_model.py .
CMD ["python", "train_model.py"]

Uses a slim base image for efficiency. Installs build tools (build-essential) for packages like prophet. Copies in your script and sets it to run by default.

Output (inside container):

Model trained successfully on 12 months of retail data.
Saved forecast plot to /output/forecast.png

Now whether you run this on your laptop, a cloud VM, or a CI pipeline, it behaves exactly the same.

2. Scrapers That Run Like Clockwork

Web scrapers often need to run on a schedule. But they fail silently when a dependency changes or your local timezone shifts. Docker gives you predictable, automatable scrapers.

scrape.py:

import sys
site = sys.argv[1] if len(sys.argv) > 1 else "default"
print(f"Scraping started for: {site}")

Dockerfile:

FROM python:3.10
WORKDIR /app
COPY scrape.py .
CMD ["python", "scrape.py", "amazon"]

Run with output directory:

docker run -v $(pwd)/output:/app/output my-scraper

Expected Output:

Scraping started for: amazon

You can now schedule this with cron, GitHub Actions, or run on any server without worrying about local setup.

3. APIs and Microservices with Flask or FastAPI

FastAPI makes building APIs in Python quick. But deploying them can be a nightmare if you're not containerized. You’ll hit issues with ports, CORS, or mismatched versions. Docker takes care of that.

Dockerfile:

FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Expected Output on Running:

INFO:     Uvicorn running on http://0.0.0.0:8000

You now have an API that can be deployed on AWS, GCP, or run locally—all with zero config drift.

4. CI/CD Test Environments That Just Work

Your tests should run the same everywhere, whether it’s your machine, staging, or a CI pipeline. That’s rarely true outside of Docker. Wrap your test runner in a container and forget about missing dependencies.

Dockerfile:

FROM python:3.9
WORKDIR /code
COPY . .
RUN pip install -r requirements.txt
CMD ["pytest"]

Run inside CI/CD:

docker build -t test-runner .
docker run test-runner

Expected Output:

================= test session starts =================
collected 12 items
✔ test_api.py::test_health_check PASSED
✔ test_models.py::test_model_load PASSED
...

This guarantees that your test suite runs the same on every commit.

5. Deploying Python to IoT or Edge Devices

IoT devices (like Raspberry Pi or Jetson Nano) often run stripped-down Linux OSes. Installing Python dependencies manually is messy and inconsistent. Containers fix that.

You build the image once, targeting ARM or x86, and deploy it wherever needed.

Python Dockerfile (for ARM):

FROM --platform=linux/arm64 python:3.9-slim
COPY edge_script.py .
CMD ["python", "edge_script.py"]

Expected Output on Device:

Sensor reading at 10:23 AM: 27.1°C
Logged to cloud successfully.

Now your edge code runs the same whether it’s on dev boards, remote sensors, or production robots.

Each of these scenarios solves a real pain point: instability, inconsistencies, and lost time.

Also Read: Top 15 Python Challenges for Beginners with Examples

With a solid understanding of Docker Python scripting, the next step is advancing your career in programming. Let’s explore how upGrad can help you deepen your knowledge of advanced Python functions.

Get Your Python Projects Docker-Ready with upGrad!

Knowing how to run a Dockerized Python script is an essential skill for scaling your applications beyond your local environment. You’ve learned how to containerize your Python code, set up your environment, and run your application seamlessly in Docker. Now, it’s time to advance your learning with practical use of your knowledge.

upGrad’s programs cut past the theory and show you exactly how teams build, ship, and run Dockerized applications in business. From setting up environments to building production workflows, it’s all project-driven and mentor-led.

Want to go hands-on with Docker and Python? Here are some relevant courses for you:

If you're ready to take the next step in your programming journey, connect with upGrad’s career counseling for personalized guidance. You can also visit a nearby upGrad center for hands-on training to enhance your skills and open up new career opportunities!

Unlock the power of data with our popular Data Science courses, designed to make you proficient in analytics, machine learning, and big data!

Explore our Popular Data Science Courses

Executive Post Graduate Programme in Data Science from IIITB	Data Science Bootcamp with AI	Master of Science in Data Science from LJMU
Advanced Certificate Programme in Data Science from IIITB	Professional Certificate Program in Data Science and Business Analytics from University of Maryland	Data Science Courses

Elevate your career by learning essential Data Science skills such as statistical modeling, big data processing, predictive analytics, and SQL!

Top Data Science Skills to Learn

Data Analysis Course	Inferential Statistics Courses
Hypothesis Testing Programs	Logistic Regression Courses
Linear Regression Courses	Linear Algebra for Analysis

Stay informed and inspired with our popular Data Science articles, offering expert insights, trends, and practical tips for aspiring data professionals!

Read our popular Data Science Articles

Data Science Career Path: A Comprehensive Career Guide	Data Science Career Growth: The Future of Work is here	Why is Data Science Important? 8 Ways Data Science Brings Value to the Business
Relevance of Data Science for Managers	The Ultimate Data Science Cheat Sheet Every Data Scientists Should Have	How to Become a Data Scientist

References:

https://www.docker.com/blog/docker-raises-series-c-build-share-run/?utm_source=chatgpt.com

https://survey.stackoverflow.co/2023/