How to Run pdb in a Docker Container: A Complete Guide (2026)

Debugging Python applications inside a Docker container can be a bit tricky, especially when you're trying to use the Python Debugger (pdb). This tutorial will guide you through the process of setting up and running pdb within a Docker container, offering a comprehensive understanding of how to troubleshoot and debug your Python applications effectively in this environment.

Key Takeaways

• Understand how to set up and configure Python pdb within Docker.
• Learn how to build and run a Docker container with pdb support.
• Explore techniques to interactively debug Python applications.
• Identify common errors and troubleshooting tips related to pdb in Docker.
• Gain insights on best practices for debugging in containerized environments.

Debugging is an essential part of software development. When it comes to containerized applications, traditional debugging methods may not work out of the box. This is where understanding how to run pdb inside Docker becomes crucial. Whether you are a seasoned developer or a beginner in container technology, being able to debug effectively can save you a lot of time and headaches.

Prerequisites

• Basic understanding of Docker and Python.
• Docker installed on your machine (Docker version 20.10.7 or later).
• Python 3.6 or later.
• A sample Python application you wish to debug.

Step 1: Set Up Your Docker Environment

Before you can run pdb inside a Docker container, you need to ensure that your Docker environment is properly set up. This involves having Docker installed and running on your machine. You can verify this by running:

docker --version

If Docker is not installed, refer to the official Docker installation guide and follow the steps for your operating system.

Step 2: Create a Dockerfile for Your Python Application

To debug your Python application, you need to create a Dockerfile that sets up your environment. Here is a simple example:

FROM python:3.6
ENV PROJECT_DIR=/opt/foo
WORKDIR $PROJECT_DIR
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "foo.py"]

This Dockerfile uses a Python 3.6 base image, sets up a working directory, copies the application code, installs dependencies, and specifies the command to run the application.

Step 3: Modify Your Python Code for pdb

To enable debugging, you need to import pdb and set a trace in your Python code. Modify foo.py as follows:

def hello_world():
    print("hello world")

if __name__ == '__main__':
    import pdb; pdb.set_trace()
    hello_world()

Here, pdb.set_trace() is used to pause execution and start the debugger.

Step 4: Build the Docker Image

With the Dockerfile and modified Python code ready, build your Docker image using the following command:

docker build -t foo .

This command will package your application into a Docker image named foo.

Step 5: Run the Docker Container with Interactive Terminal

To use pdb, you need to run your Docker container with an interactive terminal. Use the -it flag to achieve this:

docker run -it foo

Once the container starts, it will pause at the pdb prompt, allowing you to interactively debug your application.

Step 6: Debugging with pdb

At the pdb prompt, you can use various pdb commands to inspect the state of your application, step through code, and evaluate expressions. Some useful commands include:

• n: Execute the next line of code.
• c: Continue execution until the next breakpoint.
• p: Print the value of a variable.
• q: Quit the debugger.

Common Errors/Troubleshooting

While running pdb inside Docker, you might encounter some common issues:

• Docker not running: Ensure the Docker daemon is active.
• Permission errors: Run Docker commands with appropriate permissions or as a user in the Docker group.
• Missing dependencies: Verify that all required Python packages are listed in requirements.txt and installed correctly.

Conclusion

Running pdb inside a Docker container is a valuable skill for debugging Python applications in a containerized environment. By following this guide, you can set up your environment and interactively debug your code, leading to more efficient troubleshooting and development processes.

Frequently Asked Questions

Can I use pdb with other Python versions?

Yes, pdb is available with any version of Python. Just ensure your Docker base image matches the Python version you're using.

How do I add more breakpoints?

You can add more pdb.set_trace() calls at any point in your code where you need to pause execution.

Why isn't pdb stopping at my breakpoint?

Ensure you are running the Docker container with the -it flags to properly attach the interactive terminal.

Frequently Asked Questions

Can I use pdb with other Python versions?

Yes, pdb is available with any version of Python. Just ensure your Docker base image matches the Python version you're using.

How do I add more breakpoints?

You can add more pdb.set_trace() calls at any point in your code where you need to pause execution.

Why isn't pdb stopping at my breakpoint?

Ensure you are running the Docker container with the -it flags to properly attach the interactive terminal.