PuDB: the README says Python 3.6, the metadata says 3.10, and neither says how to install the release
Full-screen console debugger for Python
At a glance
- What is it?
- PuDB is a full-screen curses debugger for Python built on urwid, with pdb-style keybindings and a module browser. Its README documents only a git clone, leaves the Python floor at 3.6 while the metadata requires 3.10, and keeps its try-it script and examples directory unmentioned.
- Who is it for?
- PuDB fits someone debugging on a terminal over ssh or inside a container, who wants the source, stack, breakpoints and variables on one screen and would rather not attach a graphical debugger to a remote process. Before you install it, trust `requires-python = "~=3.10"` rather than the feature list's Python 3.6 claim, and remember that the classifiers name POSIX and Unix with no Windows entry, because the interface is a curses program built on urwid.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 5, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The feature list says 3.6, the metadata says 3.10
The last bullet of the feature list states that PuDB should work with Python 3.6 and newer, and adds that versions 2019.2 and older continue to support Python 2.7. The packaging metadata disagrees: `requires-python = "~=3.10"`, which is 3.10 and anything newer inside the 3.x line, with no 2.7 path at all. The classifiers do not settle it either, since they carry a bare `Programming Language :: Python :: 3` with no per-version entries. So the sentence a newcomer reads first describes a floor three releases below the one the install will enforce, and the only Python 2 reference is a historical footnote about a version line that ended years ago. Anyone on 3.6 through 3.9 should read the metadata rather than the prose.
The only install line in the README is a clone
Under a heading called Development Version, the README offers one command and no build step after it:
git clone https://github.com/inducer/pudb.gitThere is no pip command anywhere in the file, no mention of an extras group, and no instruction for what to run once the clone finishes. The packaged version is reachable only through the PyPI badge near the top, which points at the package page on the index. The metadata defines a console script named `pudb` bound to `pudb.run:main`, and the README never mentions that command either. It does mention controlling the debugger from a separate terminal, so a remote session is clearly an intended use, but the entry point that starts it is left to the badge.
One dependency appears twice, each bound to an issue number
The runtime list holds `jedi>=0.18,<1`, `packaging>=20.0`, `pygments>=2.19`, `urwid>=2.4`, `urwid>=2.5.1`, `urwid_readline` and `typing_extensions >= 4.13`. urwid is named twice with different floors, and the comments above those lines are links to issue 707 and to a comment under it, which is how a second constraint on the same package ended up in one list. The pygments floor of 2.19 carries a link to issue 710 in the same way. Note also the spacing: `typing_extensions >= 4.13` has spaces around the operator while nothing else in the list does. Small things, but they tell you the bounds were raised one at a time as issues came in, and the file keeps the receipts inline rather than in a changelog.
The try-it script and the examples directory go unmentioned
The repository root carries `debug_me.py` and `try-the-debugger.sh`, and there is an `examples/` directory holding five files: `mpi4py-debug.py`, `remote-debug.py`, `shell.py`, `stringifier.py` and `theme.py`. None of the seven appears in the README. So the fastest way to see the debugger work, a script named after trying it, sits next to the README unmentioned, and so do the two examples that answer the questions people actually ask: how to drive the debugger from another process, and how it behaves under MPI where each rank is a separate process. There is also a `manual-tests/` directory at the root. The README's closing sections cover the mailing list, the documentation site and the code browser, and stop there.
Two keys hand over the same power, and one opens a second session
The feature list is explicit about what the keyboard can do. `b` sets a breakpoint on the line under the pointer and `t` runs to that line. `m` opens a module browser that shows loaded modules and can load new ones and reload existing ones. `!` drops to a Python shell in the current environment, and `Ctrl-X` opens a command prompt alongside the source view. The feature list also claims the ability to control the debugger from a separate terminal, which is a third path to the same place. Navigation follows cursor keys and Vi shortcuts, with other keys inspired by the corresponding pdb commands. Read together, that is a debugger with a shell, a module loader and an out-of-band control channel, which is normal for an interactive debugger and worth naming before you attach one to a shared machine.
Two CI systems, and an sdist that prunes some files and not others
The README carries a GitLab pipeline badge pointing at gitlab.tiker.net and a GitHub Actions badge for `ci.yml`, and the repository holds both `.gitlab-ci.yml` and a `.github/` directory, so the same commits are checked in two places. The source distribution excludes `/.github`, `/.gitlab-ci.yml`, `/.mailmap`, `*~`, `/.basedpyright`, `/.coveragerc` and `/.editorconfig`. It does not exclude `examples/`, `manual-tests/`, `debug_me.py` or `try-the-debugger.sh`, so everything a person uses to try the debugger travels inside the package. Development dependencies are declared twice as well, once as a hatch environment holding basedpyright, ruff and types-Pygments, and once in `requirements.dev.txt` at the root, with ruff configured in preview mode.
The classifiers say POSIX and Unix, and there is no Windows entry
The metadata carries `Environment :: Console`, `Environment :: Console :: Curses`, `Operating System :: POSIX` and `Operating System :: Unix`, with `Topic :: Terminals` and `Topic :: Utilities`, and the status is `Development Status :: 4 - Beta`. Nothing in that list claims Windows, and the interface choice follows from the dependency list, since urwid and urwid_readline are what put a full-screen program in a terminal. That also explains the two custom themes shipped for light and dark, the dark one behind `Ctrl-P`, and the option to set a theme of your own, which is what `examples/theme.py` would be for. The one compatibility promise made in prose is that keys are inspired by the corresponding pdb commands rather than identical to them, so muscle memory from pdb is close but not guaranteed.
Screenshots from 2009 and 2020 for a 2025 release line
The visual material is old. The light and dark theme screenshots sit in `doc/images/`, and the two screencasts linked are a 2020 recording on YouTube and a 2009 one on Vimeo, while the current version in the metadata is 2025.1.5 and the release tags follow that dated scheme, v2025.1.5 on 2025-12-06 after v2025.1.4 a day earlier. The last commit on `main` is dated 2026-09-20, so the code moves faster than the screenshots. One more inconsistency worth naming: the repository's license field carries no value at all, `pyproject.toml` declares MIT, and a `LICENSE` file sits at the root, so which of those governs is something the repository does not settle for you.
Editorial conclusion
PuDB fits someone debugging on a terminal over ssh or inside a container, who wants the source, stack, breakpoints and variables on one screen and would rather not attach a graphical debugger to a remote process. Before you install it, trust `requires-python = "~=3.10"` rather than the feature list's Python 3.6 claim, and remember that the classifiers name POSIX and Unix with no Windows entry, because the interface is a curses program built on urwid. Decide how you will use the two keys that hand over execution power, `!` for a shell in the current environment and `m` for the module browser, before you point it at anything shared. If you want shell completion, install the extra, since `shtab` is not a default dependency. Anyone looking for an install command in the README will not find one; the packaged route is PyPI and the only line the README gives is a clone.
Frequently asked questions
How do I install PuDB?
The packaged version lives on PyPI as `pudb`, with a console script of the same name bound to `pudb.run:main`. The README carries no pip command at all; the only command it gives is `git clone https://github.com/inducer/pudb.git` for the development version, with nothing to run afterwards. Shell completion is a separate extra that pulls in `shtab`.
Which Python versions does PuDB support?
The packaging metadata requires `~=3.10`, so 3.10 or newer inside the 3.x line. The feature list still says it should work with Python 3.6 and newer and mentions Python 2.7 support as a property of versions 2019.2 and older, so the prose and the metadata disagree about the floor.
Which keys does PuDB use?
`b` sets a breakpoint on the pointed line, `t` runs to the line under the cursor, `m` opens the module browser, `!` drops to a Python shell in the current environment, `Ctrl-X` opens a command prompt beside the source, and `Ctrl-P` switches to a dark theme. Navigation also follows cursor keys and Vi shortcuts.
Can PuDB debug a process in another terminal or machine?
The feature list states that the debugger can be controlled from a separate terminal, and the repository carries an `examples/remote-debug.py` for it, which the README does not link. Nothing in the README describes how that connection is restricted or authenticated, and another example, `examples/mpi4py-debug.py`, covers the case where each rank is its own process.
How can I try PuDB without installing it?
The repository root holds `debug_me.py` and `try-the-debugger.sh`, neither of which the README mentions, and the `examples/` directory holds five more files covering shells, themes, remote debugging and MPI. Cloning the repository is all the README asks for before you start.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/inducer-pudb)