How to use PDB inside a docker container.

Hello there fellow, if you’re reading now this article, then you probably ran into some problems related to debugging inside a docker container by means of pdb.

There are several nuances that uncovered on the internet, so I’d like to share with others my personal experience with those. First of all, I start with the configuration part.

You need to have something like this inside your docker-compose.yml

Nuances to know:

  • It’s important to set and parameters to on every service that will use PDB.
  • Usually inside specified bundles of services like Nginx & Gunicorn, Nginx & uWSGI etc., so you need to set timeout flag for your WSGI server, because if you won’t do it, then you’ll be only limited with 1 minute (mostly default timeout for all WSGI servers) to debug something and after that, a connection will be lost, so we need to increase it for development purposes.
  • parameter should be complemented with or any other available port, you can check unavailable ports by means such command inside your terminal. Likewise, the first bullet point, on every service that will be using PDB you need to provide a port.

That’s it for file. Other problems will appear when you’ll set breakpoints by means lovely from Python standard library and alongside it, you have continuous spawning of logs to STDOUT. Yes, you can attach a docker container and jump into it, but you won’t be able to type something, because logs will always override your input.

The solution is to use library and debug it remotely by means of . So you need to add to your and set an appropriate breakpoint. E.g.:

The next step is to connect to our remote debugger by means of . You need to specify host and port that you provided inside your , but be careful, host inside our Python code always should be and port you set likewise , but host differs for . For example, if you use then, you need to figure out the IP of this machine. You can do it simply by such command and then connect by . E.g.:

  • — it’s a default case of connection if you don’t use and the scheme is next if you do
  • worth to mention, you need to connect when your Python interpreter will reach a breakpoint.

UPD: There is a fancy pdb wrapper there called pdb++. You can improve your debugging experience with this tool. All that you need is to add this fancy lib to your and you’ll get something like this when you’ll be debugging inside .

pdb++ preview from GitHub

One thing about pdb++ in sticky mode, when used by telnet, truncate an output what is not really we want. It can be changed easily. In the case of Dockerfile (or docker-compose ), we can put the following inside a bash script and use it as an ENTRYPOINT. E.g.:

Last but not least, there is an option to set argument for gunicorn and use vanilla pdb with (thanks Colin Miller). This will avoid usage of and remote-pdb library and won’t overwrite attached pdb screen with gunicorn logs. Moreover, in this case, tab autocomplete will work. See repository to learn more.

You can run from a Docker container itself too, so you won’t need to modify and use , remote-pdb and even , just don’t forget to disable logging.

So as you can see there are plenty of ways to use pdb in a docker container. I hope it was helpful for you. Cheers.

Software Engineer, LL.B., MSc in CS