Install & Compatibility
Where this runs
tested against v0.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.006s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gdbmongo
✓ import gdbmongo
✗ import gdb
The 'gdb' module is only available within GDB's embedded Python interpreter. For gdbmongo, you import 'gdbmongo' which then registers its functionality with GDB.
register_printers
✓ gdbmongo.register_printers()
Call this function within GDB's Python context (e.g., from .gdbinit) to enable the pretty printers.
To quickly integrate `gdbmongo` with GDB, add the provided Python snippet to your `~/.gdbinit` file. This script attempts to import `gdbmongo` and, if it fails, can optionally try to install it using `pip` within the GDB's Python environment (especially useful for specific toolchains). After import, it registers the essential pretty printers. You can then launch GDB and use commands like `(gdb) enable pretty-printer global gdbmongo-mongo-extras` to activate other collections.
# In your ~/.gdbinit file:
python
try:
import gdbmongo
except ImportError:
import sys
# Example: Attempt to install gdbmongo if not found (e.g., in a specific toolchain Python)
if sys.prefix.startswith('/opt/mongodbtoolchain/'): # Adjust path as needed for your environment
import subprocess
subprocess.run([sys.prefix + '/bin/python3', '-m', 'pip', 'install', 'gdbmongo'], check=True)
import gdbmongo
else:
import warnings
warnings.warn("Not attempting to install gdbmongo into non-MongoDB toolchain Python")
# Register printers if gdbmongo was successfully imported
if 'gdbmongo' in dir():
gdbmongo.register_printers(essentials=True, stdlib=False, abseil=False, boost=False, mongo_extras=False)
end
Debug
Known issues
gotchaGDB's embedded Python interpreter often uses the system's base Python installation, not necessarily a virtual environment from which GDB was launched. This can lead to `ImportError` if `gdbmongo` is installed only in a virtual environment.fixEnsure `gdbmongo` is installed in the Python environment GDB is linked against (typically the base system Python), or explicitly manage `sys.path` within your `.gdbinit` to include the virtual environment's site-packages. The provided quickstart snippet includes a conditional install attempt for specific toolchains.
affects: All versions
gotchaBy default, `gdbmongo` pretty printer collections other than `gdbmongo-essentials` are disabled to prevent conflicts with pretty printers defined in the official `mongodb/mongo` repository.fixTo enable additional pretty printers (e.g., `mongo_extras`), explicitly pass `True` to `gdbmongo.register_printers()` (e.g., `gdbmongo.register_printers(mongo_extras=True)`), or enable them later within GDB using `(gdb) enable pretty-printer global gdbmongo-mongo-extras`.
affects: All versions
gotchaDirectly `import gdb` or attempting to use GDB-specific Python functionality from a standard Python script outside of the GDB process will fail with an `ImportError`. The `gdb` module is part of GDB's embedded Python interpreter.fixAlways execute Python code that interacts with GDB's API (like `gdbmongo`) within GDB, typically by sourcing a Python script (`(gdb) source your_script.py`) or including it in your `.gdbinit` file.
affects: All versions
gotchaAs a debugging tool closely tied to the MongoDB Server's internal structures, `gdbmongo`'s functionality can be sensitive to major changes in MongoDB Server versions. Unforeseen behavior or incorrect pretty printing may occur if `gdbmongo` is used with a significantly different MongoDB Server version than it was developed for.fixRefer to the `gdbmongo` project's documentation or changelog for specific compatibility notes regarding MongoDB Server versions. Regularly update `gdbmongo` to match the version of the MongoDB Server you are debugging to ensure optimal and correct functionality.
affects: Inter-version compatibility
Errors
Common errors & fixes
MongoDB gdb extensions only support Python 3. Your GDB was compiled against Python 2
GDB was compiled with Python 2 support, but gdbmongo requires Python 3 for its pretty printers and commands.
fixInstall a version of GDB that is compiled with Python 3 support (e.g., `gdb-python3` or `gdb-multiarch` on some Linux distributions) or compile GDB from source with `--with-python=python3`.
Warning: Could not load bson library for Python '
The `bson` Python library, a dependency for `gdbmongo` to correctly handle MongoDB BSON types, is not installed or not accessible to the Python environment GDB is using.
fixInstall the `bson` library using pip: `pip install bson`. Ensure it is installed in the specific Python environment that GDB is linked against.
sh: gdb: command not found
The `gdb` executable is not installed on the system or its installation directory is not included in the system's PATH environment variable.
fixInstall GDB using your system's package manager (e.g., `sudo apt-get install gdb` on Debian/Ubuntu, `yum install gdb` on Fedora/RHEL). Verify that the GDB executable is in your system's PATH.
ModuleNotFoundError: No module named 'gdbmongo'
The `gdbmongo` Python package is not installed in the Python environment GDB is using, or GDB's Python interpreter cannot find the installed package because `sys.path` is incorrectly configured.
fixInstall `gdbmongo` using pip (`pip install gdbmongo`). Then, add a snippet to your `.gdbinit` file to explicitly load `gdbmongo`, adjusting the path to your Python site-packages if necessary: `python import sys; sys.path.insert(0, '/path/to/your/python/site-packages'); import gdbmongo; gdbmongo.register_printers()`.
Upgrade
Version history
0.16.0latest on PyPI · released Feb 13, 2025
Audit
Dependencies
pythonrequiredRequired Python version for the GDB's embedded interpreter.