Picture by Writer | Ideogram

 

# Introduction

 
Docker has simplified how we develop, ship, and run purposes by offering constant environments throughout totally different techniques. Nevertheless, this consistency comes with a trade-off: debugging turns into deceptively advanced for newcomers when your purposes — together with Python purposes — are operating inside Docker containers.

For these new to Docker, debugging Python purposes can really feel like making an attempt to repair a automobile with the hood welded shut. You recognize one thing’s fallacious, however you may’t fairly see what’s occurring inside.

This beginner-friendly tutorial will train you the way to get began with debugging Python in Docker.

 

# Why is Debugging in Docker Totally different?

 
Earlier than we dive in, let’s perceive why Docker makes debugging difficult. If you’re operating Python regionally in your machine, you may:

  • See error messages instantly
  • Edit recordsdata and run them once more
  • Use your favourite debugging instruments
  • Examine what recordsdata exist and what’s in them

However when Python runs inside a Docker container, it is usually trickier and fewer direct, particularly in the event you’re a newbie. The container has its personal file system, its personal surroundings, and its personal operating processes.

 

# Setting Up Our Instance

 
Let’s begin with a easy Python program that has a bug. Don’t fret about Docker but; let’s first perceive what we’re working with.

Create a file known as app.py:

def calculate_sum(numbers):
    whole = 0
    for num in numbers:
        whole += num
        print(f"Including {num}, whole is now {whole}")
    return whole

def most important():
    numbers = [1, 2, 3, 4, 5]
    consequence = calculate_sum(numbers)
    print(f"Closing consequence: {consequence}")
    
    # This line will trigger our program to crash!
    division_result = 10 / 0
    print(f"Division consequence: {division_result}")

if __name__ == "__main__":
    most important()

 

Should you run this usually with python3 app.py, you may see it calculates the sum appropriately however then crashes with a “division by zero” error. Simple to identify and repair, proper?

Now let’s see what occurs when this straightforward software runs inside a Docker container.

 

# Creating Your First Docker Container

 
We have to inform Docker the way to bundle our Python program. Create a file known as `Dockerfile`:

FROM python:3.11-slim

WORKDIR /app

COPY app.py .

CMD ["python3", "app.py"]

 

Let me clarify every line:

  • FROM python:3.11-slim tells Docker to begin with a pre-made Linux system that already has Python put in
  • WORKDIR /app creates an `/app` folder contained in the container and units it because the working listing
  • COPY app.py . copies your app.py file out of your pc into the `/app` folder contained in the container
  • CMD ["python3", "app.py"] tells Docker what command to run when the container begins

Now let’s construct and run this container:

docker construct -t my-python-app .
docker run my-python-app

 

You will see the output, together with the error, however then the container stops and exits. This leaves you to determine what went fallacious contained in the remoted container.

 

# 1. Operating an Interactive Debugging Session

 
The primary debugging talent you want is studying the way to get inside a operating container and verify for potential issues.

As an alternative of operating your Python program instantly, let’s begin the container and get a command immediate inside it:

docker run -it my-python-app /bin/bash

 

Let me break down these new flags:

  • -i means “interactive” — it retains the enter stream open so you may kind instructions
  • -t allocates a “pseudo-TTY” — mainly, it makes the terminal work correctly
  • /bin/bash overrides the traditional command and provides you a bash shell as an alternative

Now that you’ve got a terminal contained in the container, you may run instructions like so:

# See what listing you are in
pwd

# Record recordsdata within the present listing
ls -la

# Take a look at your Python file
cat app.py

# Run your Python program
python3 app.py

 

You will additionally see the error:

root@fd1d0355b9e2:/app# python3 app.py
Including 1, whole is now 1
Including 2, whole is now 3
Including 3, whole is now 6
Including 4, whole is now 10
Including 5, whole is now 15
Closing consequence: 15
Traceback (most up-to-date name final):
  File "/app/app.py", line 18, in 
    most important()
  File "/app/app.py", line 14, in most important
    division_result = 10 / 0
                      ~~~^~~
ZeroDivisionError: division by zero

 

Now you may:

  • Edit the file proper right here within the container (although you may want to put in an editor first)
  • Discover the surroundings to grasp what’s totally different
  • Check small items of code interactively

Repair the division by zero error (possibly change `10 / 0` to `10 / 2`), save the file, and run it once more.

The issue is mounted. If you exit the container, nevertheless, you lose observe of adjustments you made. This brings us to our subsequent approach.

 

# 2. Utilizing Quantity Mounting for Reside Edits

 
Would not or not it’s good in the event you might edit recordsdata in your pc and have these adjustments robotically seem contained in the container? That is precisely what quantity mounting does.

docker run -it -v $(pwd):/app my-python-app /bin/bash

 

The brand new half right here is -v $(pwd):/app:

  • $(pwd) outputs the present listing path.
  • :/app maps your present listing to /app contained in the container.
  • Any file you alter in your pc instantly adjustments contained in the container too.

Now you may:

  1. Edit app.py in your pc utilizing your favourite editor
  2. Contained in the container, run python3 app.py to check your adjustments
  3. Preserve modifying and testing till it really works

Here is a pattern output after altering the divisor to 2:

root@3790528635bc:/app# python3 app.py
Including 1, whole is now 1
Including 2, whole is now 3
Including 3, whole is now 6
Including 4, whole is now 10
Including 5, whole is now 15
Closing consequence: 15
Division consequence: 5.0

 

That is helpful since you get to make use of your acquainted modifying surroundings in your pc and the very same surroundings contained in the container as properly.

 

# 3. Connecting a Distant Debugger from Your IDE

 
Should you’re utilizing an Built-in Improvement Setting (IDE) like VS Code or PyCharm, you may really join your IDE’s debugger on to code operating inside a Docker container. This provides you the total energy of your IDE’s debugging instruments.

Edit your `Dockerfile` like so:

FROM python:3.11-slim

WORKDIR /app

# Set up the distant debugging library
RUN pip set up debugpy

COPY app.py .

# Expose the port that the debugger will use
EXPOSE 5678

# Begin this system with debugger assist
CMD ["python3", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "app.py"]

 

What this does:

  • pip set up debugpy installs Microsoft’s debugpy library.
  • EXPOSE 5678 tells Docker that our container will use port 5678.
  • The CMD begins our program by means of the debugger, listening on port 5678 for a connection. No adjustments to your Python code are wanted.

Construct and run the container:

docker construct -t my-python-app .
docker run -p 5678:5678 my-python-app

 

The -p 5678:5678 maps port 5678 from contained in the container to port 5678 in your pc.

Now in VS Code, you may arrange a debug configuration (in .vscode/launch.json) to connect with the container:

{
    "model": "0.2.0",
    "configurations": [
        {
            "name": "Python: Remote Attach",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            }
        }
    ]
}

 

If you begin debugging in VS Code, it is going to connect with your container, and you may set breakpoints, examine variables, and step by means of code identical to you’d with native code.

 

# Widespread Debugging Issues and Options

 
“My program works on my pc however not in Docker”

This normally means there is a distinction within the surroundings. Examine:

  • Python model variations.
  • Lacking dependencies.
  • Totally different file paths.
  • Setting variables.
  • File permissions.

“I am unable to see my print statements”

  • Use python -u to keep away from output buffering.
  • Be sure to’re operating with -it in order for you interactive output.
  • Examine in case your program is definitely operating as meant (possibly it is exiting early).

“My adjustments aren’t exhibiting up”

  • Be sure to’re utilizing quantity mounting (-v).
  • Examine that you simply’re modifying the precise file.
  • Confirm the file is copied into the container.

“The container exits instantly”

  • Run with /bin/bash to examine the container’s state.
  • Examine the error messages with docker logs container_name.
  • Be certain that your CMD within the Dockerfile is right.

 

# Conclusion

 
You now have a fundamental toolkit for debugging Python in Docker:

  1. Interactive shells (docker run -it ... /bin/bash) for exploring and fast fixes
  2. Quantity mounting (-v $(pwd):/app) for modifying in your native file system
  3. Distant debugging for utilizing your IDE’s full capabilities

After this, you may attempt utilizing Docker Compose for managing advanced purposes. For now, begin with these easy methods. Most debugging issues might be solved simply by getting contained in the container and poking round.

The secret’s to be methodical: perceive what needs to be occurring, determine what is definitely occurring, after which bridge the hole between the 2. Joyful debugging!
 
 

Bala Priya C is a developer and technical author from India. She likes working on the intersection of math, programming, information science, and content material creation. Her areas of curiosity and experience embody DevOps, information science, and pure language processing. She enjoys studying, writing, coding, and occasional! Presently, she’s engaged on studying and sharing her information with the developer neighborhood by authoring tutorials, how-to guides, opinion items, and extra. Bala additionally creates partaking useful resource overviews and coding tutorials.