# GNU Radio: the signal processing runtime behind software-defined radio

> GNU Radio is a GPL-3.0 signal processing toolkit and runtime, built in C++ with Python bindings and the GNU Radio Companion flowgraph editor. It is the standard open stack for SDR work, but the install path decides how much pain you meet.

**gnuradio/gnuradio** — GNU Radio – the Free and Open Software Radio Ecosystem

- Repository: https://github.com/gnuradio/gnuradio
- Website: https://gnuradio.org
- Stars: 6,274 · Forks: 2,162
- Language: C++
- License: GPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/gnuradio-gnuradio

## What GNU Radio is for, and who ends up using it

GNU Radio is a signal processing runtime plus a development toolkit. The README describes it as originally built for software-defined radios and for simulating wireless communications, and says that adoption spread into hobbyist, academic and commercial settings. The listed domains go well past radio: digital communications, nuclear physics, high-energy particle physics, astrophysics and radio astronomy. That list is the clearest statement of who the project is for. It is not a consumer app with a device list. It is infrastructure for people who want to describe a signal chain, run it against live or recorded samples, and change the chain without rewriting the whole program.

The practical audience splits in two. One group writes Python or C++ against the runtime and treats the flowgraph as an object graph. The other group lives in GNU Radio Companion, the graphical editor, and wires blocks together visually. The repository supports both: grc/ holds the companion application, while gnuradio-runtime/ holds the scheduler and buffer machinery underneath. A third group, smaller, writes new blocks in C++ because they need throughput that Python cannot give them.

If your goal is to press a button and hear a station, GNU Radio is more machinery than you need. If your goal is to understand or modify what happens between the antenna and the demodulated bits, it is the layer where that work is normally done.

## How a flowgraph actually runs: blocks, buffers and the scheduler

A GNU Radio program is a directed graph of blocks connected by streams of samples. Each block declares input and output ports with a type (complex float, float, byte, and so on), and the runtime moves data between them. The repository layout shows this directly: gr-blocks/ holds the general-purpose blocks, gr-filter/ the filters, gr-fft/ the transform work, gr-digital/ the modulation and coding pieces, gr-fec/ forward error correction, gr-uhd/ the USRP hardware interface, gr-soapy/ the SoapySDR interface, and gr-qtgui/ the graphical sinks.

The scheduler is the part worth understanding before you debug anything. Blocks do not call each other. The runtime decides which block has enough input and enough output space to run, then calls its work function. That means backpressure is real: a slow sink stalls the blocks feeding it, and a source that produces faster than the chain consumes will eventually hit buffer limits. Most confusing behaviour in a live flowgraph, from dropped samples to a stalled display, traces back to that arrangement rather than to the DSP itself.

The Python layer is a binding over the C++ runtime, not a reimplementation. The project's own README answers the language question implicitly: the primary language is C++, and the repository is dominated by C++ module directories, with Python used for bindings, the companion, and user scripts. So a Python flowgraph is a control surface over C++ blocks that do the sample-by-sample work.

## Installing GNU Radio and running a first flowgraph

The README calls prebuilt binary packages the recommended way to install GNU Radio on most platforms. On Debian, Ubuntu and derivatives the command it gives is a single apt install. The version you get is whatever your distribution carries, which is the first thing to check after installing.

```bash
sudo apt install gnuradio
```

For Ubuntu specifically, the README points to PPAs maintained on launchpad.net that carry both released builds and builds pulled from the main branch. It adds a warning in bold: uninstall any previously installed version of GNU Radio first. Mixing a distribution package with a PPA build is a known way to end up with two libraries on the system.

Once installed, the companion is the fastest way to see the runtime work. The README gives the command for the Qt version of GNU Radio Companion, and notes that dark mode and GUI tests need extra Python packages first.

```bash
pip install pytest-qt pyautogui QDarkStyle
gnuradio-companion --qt
```

The companion opens as a canvas. You drag a source block and a sink block onto it, connect an output port to an input port, and press the run button. The README's own screenshots show exactly this shape: a flowgraph in the editor, the generated Python code beside it, and the output window. That generated code is worth reading once, because it shows how the visual graph becomes runtime calls.

If you are on Windows, macOS, a Raspberry Pi or another platform, the README does not give per-platform commands. It sends you to the wiki page InstallingGR, section Quick Start, and to a second wiki page for other installation methods. Building from source is documented on a separate wiki page, LinuxInstall, section From Source. The README explicitly says PyBOMBS is no longer recommended for installing modern versions, so treat any older tutorial that starts with pybombs as stale.

## Where GNU Radio gets in your way

The install story is the first real limitation, and it is not a small one. The README's recommended path is a distribution package, which means your GNU Radio version is tied to your operating system release. The most recent release listed in the repository is v3.10.12.0 from 2025-02-20, with v3.10.11.0 before it in 2024-07-24. A distribution that froze earlier will hand you something older, and blocks or parameters added later will simply not exist in your install. The PPA route fixes that on Ubuntu and creates the uninstall-first requirement in exchange.

The second limitation is hardware coupling. GNU Radio itself does not talk to radios. Hardware access comes through blocks such as gr-uhd for USRP devices and gr-soapy for the SoapySDR abstraction. If your device has no source block in your install, GNU Radio cannot see it, no matter how the flowgraph is drawn. That is a packaging and driver question before it is a GNU Radio question.

The third is the scheduler model described above. It rewards flowgraphs that are roughly balanced in rate and punishes ones that are not. A chain that produces bursts into a real-time sink will drop samples, and the runtime will not silently fix the rate mismatch for you.

Finally, version 4.0 is a separate repository. The README states that the next major release is under active development in the official GNU Radio 4 repo, github.com/gnuradio/gnuradio4. That is a different codebase, not a branch of this one. Anyone planning around 4.0 is planning around a project that has not shipped here.

## GNU Radio Companion versus writing the flowgraph in Python

The real choice inside GNU Radio is not which library to use, it is which authoring mode. Companion gives you a canvas, a block catalogue, and a generated Python file. Hand-written Python gives you the same runtime with variables, loops and functions around it.

Companion wins for exploration. Changing a filter tap count or a sample rate is a field edit and a rerun, and the README's screenshots show the editor, the generated code and the output side by side, which makes the mapping between the two visible. It also wins for sharing: a .grc file is a readable description of a signal chain that another person can open and inspect.

Hand-written Python wins the moment the flowgraph needs to change at runtime, or the moment you want the same chain instantiated several times with different parameters, or the moment you want to drive it from a test harness. Companion generates code, but the generated file is an output, not a place to build a larger program. Teams that push far enough usually end up with both: Companion to find the shape of the chain, Python to run it in production.

There is no wrong answer here, but there is a common mistake. People build something in Companion, outgrow it, and keep editing the generated file by hand. The next regeneration overwrites that work.

## Alternatives, and the difference that matters

The closest alternative in practice is not another general toolkit but a single-purpose decoder. Tools built around one protocol or one chipset hide the flowgraph entirely: you point them at a device and get output. That is a genuinely different approach, and for one fixed signal it is less work than assembling blocks. The trade-off is that when the signal is not the one the tool was written for, you have no layer to modify. GNU Radio's cost is setup and graph design; its return is that every stage between samples and bits is something you can replace.

A second comparison is against writing the DSP yourself in Python with NumPy and a device library. For a short chain this is often faster to get running, because there is no block catalogue to learn and no scheduler to reason about. It stops scaling when the chain grows, when you need blocks that already exist (filters, FEC, modulation), or when you want a graphical view of the running system. GNU Radio is what that hand-rolled script turns into after enough stages.

A third is the language question. Because the heavy lifting is C++ and the control surface is Python, GNU Radio is not a Python DSP library in the NumPy sense. If you want array operations over sample buffers and nothing else, NumPy is the smaller tool. If you want a running graph with hardware sources and graphical sinks, it is not.

## Licence, maintenance and what an upgrade costs

GNU Radio is GPL-3.0, with the licence file at COPYING in the repository root. The practical consequence is the usual one for a GPL runtime: linking your own blocks against it brings the combined work under the same terms, and the project's distribution model is built around that. This is a description of the licence, not legal advice; if you are shipping a closed product on top of GNU Radio, that question belongs with someone qualified to answer it. The README's legal section deals only with copyright year ranges in source headers, not with linking questions.

On maintenance, the repository is not archived and the last push was on 2026-08-27. That is recent activity. The release cadence visible here is slower than the commit cadence: v3.10.12.0 in February 2025 and v3.10.11.0 in July 2024, with a release candidate for the former two weeks earlier. So the project moves continuously but tags releases on a roughly annual rhythm within the 3.10 line.

Upgrade cost is where the two install paths diverge. With a distribution package, an upgrade is tied to your operating system release and you may skip several minor versions at once, which is where block and API changes bite. With the Ubuntu PPA, you get closer to current but must uninstall the previous version first, as the README warns. Building from source gives the most control and the largest maintenance burden, since you own the rebuild when a dependency moves. The repository's VERSIONING file and CHANGELOG.md are the places to read before a jump, and neither is summarized in the README.

## Conclusion

Adopt GNU Radio if you are building SDR receivers, digital communications chains or instrument-style DSP pipelines and you want the signal chain expressed as a flowgraph rather than as glue code. Do not adopt it if you only need to decode one fixed protocol on one dongle; a single-purpose decoder will get you there with less setup. Before committing, verify which version your distribution ships, whether your hardware has a gr-uhd or gr-soapy source block for it, and whether your target platform has a prebuilt package at all.

## FAQ

### What is GNU Radio used for?

The README describes it as a signal processing runtime and development toolkit, originally for software-defined radios and wireless simulation, with adoption in software-defined radio, digital communications, nuclear physics, high-energy particle physics, astrophysics and radio astronomy.

### Is GNU Radio still used?

The repository is not archived and the last push was on 2026-08-27, with v3.10.12.0 released on 2025-02-20. The README also notes that a next major release, GNU Radio 4.0, is under development in a separate repository.

### Can GNU Radio run on Windows?

The README does not give Windows commands. It points to the wiki page InstallingGR, section Quick Start, for other operating systems and versions, and to a separate page for other installation methods.

### Is GNU Radio written in Python?

The primary language of the repository is C++, and the module directories such as gr-blocks, gr-filter and gr-fft are C++ code. Python is used for the bindings and for GNU Radio Companion, so a Python flowgraph drives C++ blocks underneath.

### How do I install GNU Radio on Ubuntu?

The README's recommended path is the distribution package, installed with sudo apt install gnuradio. For newer builds on Ubuntu it points to PPAs on launchpad.net and warns that any previously installed version must be uninstalled first.

### How do I use GNU Radio Companion?

The README gives the command gnuradio-companion --qt to run the Qt version, after installing pytest-qt, pyautogui and QDarkStyle with pip if you want dark mode and GUI tests. The companion is the graphical editor where blocks are placed and connected into a flowgraph.

## Sources

- [gnuradio/gnuradio on GitHub](https://github.com/gnuradio/gnuradio)
- [License: GPL-3.0](https://github.com/gnuradio/gnuradio/blob/main/LICENSE)
- [Project website](https://gnuradio.org)
- [README](https://github.com/gnuradio/gnuradio/blob/main/README.md)
- [Releases](https://github.com/gnuradio/gnuradio/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gnuradio-gnuradio