---
id: freertos-gdb
version: "1.0.4"
license: Apache License 2.0
license_treatment: permissive
maintenance: dormant
---

# freertos-gdb — Python module for operating with freeRTOS-kernel objects in GDB

License: permissive · Maintenance: dormant · Downloads: 883.1K/mo

## What it is and what it does

freertos-gdb is a Python module that extends GDB's command set to make freeRTOS kernel state human-readable. It registers a `freertos` command with subcommands (`task`, `queue`, `semaphore`, `timer`) that query the running kernel and format task stacks, queue depths, semaphore holders, and timer states into readable tables. You install it via pip, then load it into GDB with a Python import—either interactively or by adding the import to your `.gdbinit` file.

The module is designed for embedded developers debugging freeRTOS applications on microcontrollers. It has no runtime dependencies beyond Python itself and GDB's Python support. The package is in Beta status and has not been actively maintained since early 2025, but the core functionality is stable and the use case is narrow enough that dormancy is not unusual for specialized debugging tools.

Use it for:

- Inspect all running tasks, their priorities, stack usage, and current state during a debug session.
- View queue contents and which tasks are blocked waiting to send or receive, helping diagnose deadlocks.
- Check semaphore and mutex holders and recursion counts to debug synchronization problems.
- Monitor active timers and their periods to verify timer-driven behavior in real-time kernel debugging.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A GDB Python plugin that adds commands to inspect and display freeRTOS kernel objects—tasks, queues, semaphores, and timers—directly from the debugger.

Yes, if you debug freeRTOS applications in GDB. The package is low-friction to install, has no external dependencies, and solves a real problem—raw kernel memory inspection is tedious without it. Dormant maintenance is acceptable here because the plugin targets a stable, narrow API. Not relevant if you don't use freeRTOS or don't debug with GDB.

## Install

pip install freertos-gdb
uv add freertos-gdb
poetry add freertos-gdb

## Installing freertos-gdb

Before you install: Low friction: pure Python wheel with no runtime dependencies. Dormant maintenance (last commit 2025-02-03), but the repository is not archived and the package targets a stable, narrow use case.

License in practice: Apache License 2.0 is permissive; you may use, modify, and distribute this package with minimal restriction, provided you include a copy of the license.

Quickstart:

pip install freertos-gdb

Then in GDB:
python import freertos_gdb

(gdb) freertos task
(gdb) freertos queue
(gdb) freertos semaphore
(gdb) freertos timer

GDB must be built with Python 3.6+ support. Verify with: gdb -q -ex "python print('OK' if sys.version_info.major==3 and sys.version_info.minor>=6 else 'NOT SUPPORTED')" -ex "quit"

Verify before relying:

- Whether the plugin works correctly with all freeRTOS kernel versions and GDB versions beyond those tested.
- Performance impact when inspecting large numbers of tasks, queues, or semaphores in a single session.
- Compatibility with GDB frontends or IDEs that embed GDB (e.g., VS Code, CLion).

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 883.1K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

freertos gdb debugger plugin, gdb kernel object inspection, freertos task queue inspection, embedded systems debugging, rtos gdb extension, freertos kernel visualization, gdb python plugin, embedded-debugging, freertos, gdb-plugin

[View on SkillFed](https://skillfed.io/packages/freertos-gdb) · [View on PyPI](https://pypi.org/project/freertos-gdb/)