# drgn

drgn (pronounced “dragon”) is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel:

    >>> from drgn.helpers.linux import list_for_each_entry
    >>> for mod in list_for_each_entry('struct module',
    ...                                prog['modules'].address_of_(),
    ...                                'list'):
    ...    if mod.refcnt.counter > 10:
    ...        print(mod.name)
    ...
    (char [56])"snd"
    (char [56])"evdev"
    (char [56])"i915"

Although other debuggers like GDB have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well-suited for introspecting the complex, inter-connected state in large programs.

Additionally, drgn is designed as a library that can be used to build debugging and introspection tools; see the official tools.

drgn was developed at Meta for debugging the Linux kernel (as an alternative to the crash utility), but it can also debug userspace programs written in C. C++ support is in progress.

In addition to the main Python API, an experimental C library, `libdrgn`, is also available.

See the Installation instructions. Then, start with the User Guide.

## Getting Help

- The GitHub issue tracker is the preferred method to report issues.

- There is also a Linux Kernel Debuggers Matrix room.

## License

Copyright (c) Meta Platforms, Inc. and affiliates.

drgn is licensed under the LGPLv2.1 or later.

## Acknowledgements

drgn is named after this because dragons eat dwarves.

## Table of Contents

Using drgn

- Installation
  - Dependencies
  - Installation
    - Package Manager
    - pip
    - From Source
    - Virtual Environment
  - Running Locally
- User Guide
  - Quick Start
  - Core Concepts
    - Programs
    - Objects
    - Helpers
  - Other Concepts
    - Threads
    - Stack Traces
    - Symbols
    - Types
    - Modules
    - Platforms
  - Command Line Interface
    - Script Mode
    - Interactive Mode
  - Next Steps
- Advanced Usage
  - Modules and Debugging Symbols
    - Loading Debugging Symbols From Non-Standard Locations
    - Loading Debugging Symbols For Specific Modules
    - Loading Additional Debugging Symbols
    - Listing Modules
    - Overriding Modules
    - Debugging Information Finders
  - Writing Plugins
  - Library
  - C Library
  - Custom Programs
  - Environment Variables
  - Linux Kernel Special Objects
- Getting Debugging Symbols
  - Building With Debugging Symbols
  - Debugging Symbols for Linux Distribution Packages
    - Debuginfod
    - Fedora
    - CentOS Stream
    - Debian
    - Ubuntu
    - Arch Linux
    - openSUSE
    - Oracle Linux

Tutorials

- Tutorials
  - Stack Traces and Mystery Addresses (blk-rq-qos Crash)
    - Setup
    - Starting With Dmesg
    - Stack Trace in drgn
    - Tracing Local Variables
    - Identifying Mystery Addresses
    - Other Stacks
    - Analysis
    - The Fix
    - Conclusion
    - Bonus Challenge: Reading File Pages
- Case Studies
  - Recovering a dm-crypt Encryption Key
    - Setup
    - Getting from Device Mapper to the Crypto API
    - Descending Down the Crypto API
    - Extracting the AES Key
    - Conclusion
  - Using Stack Trace Variables to Find a Kyber Bug

Reference

- API Reference
  - Programs
    - `Program`
    - `ProgramFlags`
    - `FindObjectFlags`
    - `ObjectNotFoundError`
    - `DebugInfoOptions`
    - `KmodSearchMethod`
    - `Thread`
    - Filenames
    - Program Constructors
    - Default Program
    - Platforms
    - Languages
  - Objects
    - `Object`
    - `AbsenceReason`
    - `NULL()`
    - `cast()`
    - `implicit_convert()`
    - `reinterpret()`
    - `container_of()`
  - Symbols
    - `Symbol`
    - `SymbolBinding`
    - `SymbolKind`
    - `SymbolIndex`
  - Stack Traces
    - `stack_trace()`
    - `StackTrace`
    - `StackFrame`
  - Types
    - `Type`
    - `TypeMember`
    - `TypeEnumerator`
    - `TypeParameter`
    - `TypeTemplateParameter`
    - `TypeKind`
    - `TypeKindSet`
    - `PrimitiveType`
    - `Qualifiers`
    - `alignof()`
    - `offsetof()`
    - Type Constructors
  - Modules
    - `Module`
    - `MainModule`
    - `SharedLibraryModule`
    - `VdsoModule`
    - `RelocatableModule`
    - `ExtraModule`
    - `ModuleFileStatus`
    - `WantedSupplementaryFile`
    - `SupplementaryFileKind`
    - Module Lookups/Constructors
  - Miscellaneous
    - `sizeof()`
    - `execscript()`
    - `IntegerLike`
    - `Path`
  - Exceptions
    - `FaultError`
    - `MissingDebugInfoError`
    - `ObjectAbsentError`
    - `OutOfBoundsError`
  - CLI
    - `version_header()`
    - `default_globals()`
    - `run_interactive()`
  - Plugins
    - `drgn_prog_set()`
  - Logging
  - Thread Safety
- Helpers
  - `ValidationError`
  - Common
    - Formatting
    - Memory
    - Program Decorators
    - Stack
    - Types
  - Linux Kernel
    - Bitmaps
    - Bit Operations
    - Block Layer
    - Boot
    - BPF
    - Cgroup
    - Common
    - CPU Masks
    - Devices
    - Virtual Filesystem Layer
    - HugeTLB
    - IDR
    - Kallsyms
    - Kconfig
    - Kernfs
    - Kernel Threads
    - Linked Lists
    - Nulls Lists
    - Lockless Lists
    - Maple Trees
    - Memory Management
    - Memory Zones
    - Modules
    - Networking
    - NUMA Node Masks
    - Panic
    - Per-CPU
    - Process IDS
    - Priority-Sorted Lists
    - Log Buffer
    - Radix Trees
    - Red-Black Trees
    - CPU Scheduler
    - Slab Allocator
    - Stack Depot
    - Swap Space
    - Traffic Control (TC)
    - TCP
    - Timekeeping
    - Users
    - Virtual Memory Statistics
    - Wait Queues
    - XArrays
  - Experimental
    - Kmodify
- Man Page
  - Synopsis
  - Description
  - Options
    - Program Selection
    - Debugging Symbols
    - Debugging Symbol Directories
    - Logging
    - Generic Information
- Support Matrix
  - Architectures
    - Cross-Debugging
  - Linux Kernel Versions
    - Kernel Configuration
- Release Highlights
  - 0.0.33 (Released October 30th, 2025)
    - Lots of New Helpers
    - Address Identification Improvements
    - Array Slices
    - More Reliable Interrupt Stack Traces
    - Kmodify Bit Field Fix
    - Linux 6.17 and 6.18 Support
    - No More Python 3.6 & 3.7 Support
  - 0.0.32 (Released June 18th, 2025)
    - MiniDebugInfo Symbol Support
    - Page Pool Helper and Leak Scripts
    - Timekeeping Helpers
    - CPU Mask Weight Helpers
    - Relative Paths for `--debug-directory`
    - Bug Fixes
    - Linux 6.16 Support
    - Last Release With Python 3.6 & 3.7 Support
  - 0.0.31 (Released April 16th, 2025)
    - Module API
    - Options for Finding Debugging Symbols
    - Stricter Debugging Symbol File Matching
    - Debuginfod Integration
    - Custom Debugging Information Finders
    - Plugins
    - Running Code Snippets on the Command Line
    - Kernel Stack Unwinding Without Debugging Symbols
    - Linux 6.14 and 6.15 Support
  - 0.0.30 (Released December 18th, 2024)
    - Symbol Index and Kallsyms
    - New Python 3.13 REPL
    - Stack Tracing Through Interrupt Handlers
    - Linux 6.13 Support
  - 0.0.28 & 0.0.29 (Released October 7th & 8th, 2024)
    - Calling Arbitrary Functions in the Running Kernel
    - Writing to Kernel Memory
    - More C Operators
    - Kernel Module Helpers
    - Thread Names
    - Full 32-Bit Arm Support
    - AArch64 and s390x Virtual Address Translation Fixes
    - Linux 6.11 and 6.12 Support
  - 0.0.27 (Released July 1st, 2024)
    - Finding the Type Member at an Offset
    - Identifying Memory
    - Configurable Type and Object Finders
    - Symbol Finders
    - `contrib` Directory
    - Linux 6.9 and 6.10 Support
  - 0.0.26 (Released March 11th, 2024)
    - Miscellaneous Helpers
    - `fsrefs.py` Tool
    - DWARF Package Files
    - Linux 6.8 Support
    - Python 3.13 Support
  - 0.0.25 (Released December 1st, 2023)
    - Omitting the `prog` Argument
    - Running Without `root`
    - Maple Tree Helpers
    - VMA Helpers
    - Wait Queue Helpers
    - ppc64 Radix MMU Support
  - 0.0.24 (Released September 8th, 2023)
    - Linked List Length Helper
    - Networking Helpers
    - C++ Lookups
    - Split DWARF
    - Performance Improvements
  - 0.0.23 (Released June 28th, 2023)
    - Virtual Address Translation Helpers
    - Vmalloc/Vmap Address Translation Helpers
    - `contrib` Directory
    - Embedding Interactive Mode
    - Full s390x Support
    - Linux 6.3 & 6.4 Support
    - Python 3.12 Support
  - 0.0.22 (Released January 5th, 2023)
    - Listing Stack Frame Locals
    - Merged Slab Caches
    - Slab Address Information
    - Annotated Stack Memory
    - XArray Helpers
    - s390x Support
    - Relicensing to LGPL