GNU Radio on Linux — Complete Setup, Flowgraph and Ham Radio Guide

What is GNU Radio and who it is for

GNU Radio is a free and open-source software development toolkit that provides signal processing blocks for implementing software radios. Where GQRX is a ready-to-use receiver application and OpenWebRX is a ready-to-use server, GNU Radio is the underlying framework that both are built on. It gives you the tools to build any signal processing application you can imagine — receivers, transmitters, decoders, analyzers, and more.

The central concept in GNU Radio is the flowgraph — a visual representation of a signal processing pipeline where data flows from a source (SDR hardware, file, or generated signal) through a chain of processing blocks (filters, demodulators, decoders) to a sink (audio output, file, or display). You build these flowgraphs either visually in GNU Radio Companion or programmatically in Python.

GNU Radio is not a replacement for GQRX or OpenWebRX for everyday monitoring — it is overkill for simply listening to amateur radio. Its strength is implementing custom signal processing that no existing application provides: decoding a proprietary protocol, building a custom transceiver, implementing a new digital mode, or doing SDR research.

Who should learn GNU Radio

• Operators who want to implement custom decoders for digital modes not supported by existing software
• Experimenters building software-defined transceivers for satellite operation or microwave work
• Students and researchers working in signal processing and wireless communications
• Developers who want to understand how GQRX, OpenWebRX, and WSJT-X work under the hood
• Contesters and DXers interested in advanced SDR techniques like I/Q signal analysis

Installation on Ubuntu and Debian

Ubuntu 22.04 and 24.04

This installs the GNU Radio runtime, development headers, the OsmoSDR source block (supports RTL-SDR, HackRF, Airspy, and more), and Python bindings. The installation is large — expect 500 MB to 1 GB of packages.

Install SDR hardware support

Build GNU Radio from source (latest version)

The repository version may be one or two major releases behind. For the latest features build from source using PyBOMBS or cmake directly:

Verify installation

GNU Radio Companion — the visual flowgraph editor

GNU Radio Companion (GRC) is the graphical editor for building flowgraphs. It provides a canvas where you drag and drop signal processing blocks and connect them with wires to create a signal processing pipeline.

Launching GRC

The GRC interface

• Canvas (center) — where you place and connect blocks to build your flowgraph
• Block library (right) — searchable list of all available signal processing blocks organized by category
• Properties panel — double-click any block to configure its parameters
• Toolbar — run, stop, and generate buttons at the top

What GRC does when you click Run

When you run a flowgraph GRC generates Python code from your visual design and executes it. The generated .py file is saved alongside your .grc file. You can read and modify this Python file directly — everything GRC does visually is plain Python using the GNU Radio API.

Block categories relevant to ham radio

Key concepts — sources, sinks, and signal processing blocks

Sample rate and decimation

The sample rate flowing through your flowgraph is the most important parameter to understand. Every block in the chain must handle samples at compatible rates. The SDR hardware produces samples at the configured rate (e.g. 2,400,000 samples/second for RTL-SDR). Decimation reduces this rate — a decimation of 10 produces 240,000 samples/second. After decimation the signal occupies a narrower bandwidth appropriate for a single channel.

Complex (I/Q) vs real signals

SDR hardware outputs complex samples — pairs of I (in-phase) and Q (quadrature) values that together represent both amplitude and phase. GNU Radio blocks that work with SDR input use complex data types (complex float). After demodulation the signal becomes real (a single audio stream). Wires in GRC are colour-coded: blue for complex, orange for float.

Frequency translation

The SDR is tuned to a center frequency. Signals at other frequencies appear offset from center in the passband. A Frequency Xlating FIR Filter block simultaneously shifts a signal from its offset position to baseband (0 Hz) and applies a low-pass filter to select only that signal — this is the standard way to select a single channel from the wide SDR input.

Variables in GRC

Use Variable blocks to define values used across multiple blocks — sample rate, center frequency, gain. Changing a variable automatically updates all blocks that reference it. This is cleaner than setting the same value in multiple places.

Building your first receiver flowgraph

The simplest useful flowgraph receives wideband FM broadcast radio from an RTL-SDR. Here is the block chain and how to build it in GRC.

Blocks needed

1. Options block — already present in every new flowgraph, set title and generate options
2. Variable block — set samp_rate = 2000000
3. RTL-SDR Source — from Sources category, set sample rate to samp_rate variable
4. WBFM Receive — from Modulators category, handles FM demodulation
5. Rational Resampler — converts from FM output rate to audio rate
6. Audio Sink — plays the demodulated audio through speakers
7. QT GUI Frequency Sink — optional waterfall display

Step-by-step in GRC

1. Open GRC and create a new flowgraph (File → New)
2. Double-click the Options block and set Generate Options to QT GUI
3. Add a Variable block, name it samp_rate, value 2000000
4. Add a Variable block, name it freq, value 100000000 (100 MHz — change to a local FM station)
5. Search for "RTL-SDR Source" in the block library and drag it to the canvas
6. Double-click it and set Sample Rate to samp_rate, Frequency to freq
7. Add a WBFM Receive block, set Quadrature Rate to 500000
8. Add a Rational Resampler, set Decimation to 10, Interpolation to 1 (converts 500000 → 48000 ksps)
9. Add an Audio Sink, set Sample Rate to 48000
10. Connect blocks: RTL-SDR → WBFM Receive → Rational Resampler → Audio Sink
11. Click Run — you should hear the FM broadcast station

Adding a waterfall display

Add a QT GUI Frequency Sink block and connect it to the output of the RTL-SDR Source (you can split one output to multiple blocks). Set the bandwidth to samp_rate. When you run the flowgraph a spectrum display window opens alongside the running receiver.

FM broadcast receiver walkthrough

Here is the complete Python script that GRC generates for a basic FM receiver — useful for understanding how flowgraphs translate to code and for running without GRC:

Ham radio applications

GNU Radio is particularly powerful for ham radio applications where existing software does not exist or does not meet your needs.

Narrowband FM — VHF/UHF amateur repeaters

Replace the WBFM Receive block with an NBFM Receive block for VHF/UHF repeater monitoring. Add a Frequency Xlating FIR Filter before the demodulator to select a specific repeater channel from the wide SDR bandwidth. This lets you monitor multiple repeaters simultaneously by running multiple parallel demodulator chains from the same RTL-SDR input.

SSB demodulation for HF

SSB demodulation in GNU Radio uses a Frequency Xlating FIR Filter (to shift the signal to baseband) followed by a Complex to Real block or a Hilbert transform. For HF operation with RTL-SDR enable direct sampling mode in the device arguments: osmosdr.source(args="rtl=0,direct_samp=2").

CW decoder

Build a CW decoder by: selecting a narrow bandwidth with a bandpass filter, applying power detection to find the CW key-on and key-off transitions, measuring timing to determine dit and dah lengths, and decoding against a Morse code lookup table. Several out-of-tree modules implement this — search for gr-morse in the GNU Radio community.

SSTV reception

Pipe the audio output of a GNU Radio SSB receiver to QSSTV via a virtual audio device. GNU Radio handles the HF reception and SSB demodulation, QSSTV handles the SSTV image decoding. This workflow is identical to using GQRX + QSSTV but gives you more control over the receive chain parameters.

Spectrum monitoring and recording

Record entire band segments as I/Q files using a File Sink block. A 2.4 MHz wide recording of the 20m band captures all activity simultaneously. Play back the file later and tune to any frequency within the recorded bandwidth. This is extremely useful for contest analysis — record the entire contest and review any QSO after the fact.

AX.25 packet radio with GNU Radio

GNU Radio can decode AX.25 packet radio frames directly, making it a software TNC for APRS and traditional packet without needing Direwolf or hardware TNCs. The gr-satellites out-of-tree module includes AX.25 decoders optimized for both 1200 baud AFSK and 9600 baud FSK.

Basic AX.25 / APRS receive chain

gr-satellites for satellite packet decoding

The gr-satellites project by Daniel Estévez EA4GPZ is the most comprehensive out-of-tree module for decoding amateur satellite telemetry. It supports AX.25, KISS, and dozens of satellite-specific protocols from OSCAR satellites, CubeSats, and LEO experimental satellites.

Connecting GNU Radio decoded packets to Direwolf

Output decoded AX.25 frames from GNU Radio as KISS frames over a TCP socket. Connect Direwolf (or any other AX.25 application) to this socket as a software TNC. This hybrid approach uses GNU Radio's superior signal processing for demodulation and Direwolf's established iGate and digipeater logic for the APRS application layer.

Satellite signal decoding

GNU Radio excels at satellite signal processing. The combination of flexible signal processing blocks, gr-satellites, and Gpredict for Doppler correction makes it the most capable open-source satellite decoding toolkit available.

Weather satellite APT reception (NOAA)

NOAA weather satellites transmit APT (Automatic Picture Transmission) images on ~137 MHz. The receive chain is straightforward:

Linear transponder satellites (SSB/CW)

Many amateur OSCAR satellites have linear transponders that relay SSB and CW contacts. Receiving them requires Doppler-corrected SSB demodulation. Use Gpredict to update the GNU Radio center frequency via the Hamlib remote control interface, or write a Python script using the ephem library to calculate and apply Doppler correction in real time.

FM satellites — AO-91, AO-92

Several amateur satellites use FM transponders. The receive chain is a standard NBFM receiver with Doppler correction. The signal sweeps across several kHz during a pass as the satellite's velocity changes the received frequency.

Using gr-satellites for CubeSat telemetry

The gr-satellites module includes pre-built flowgraphs for decoding telemetry from hundreds of amateur CubeSats. Run the included example flowgraphs to receive and decode satellite telemetry during a pass. Decoded data uploads automatically to the SatNOGS network if configured.

Python scripting with GNU Radio

Every GNU Radio flowgraph is Python code. You can write GNU Radio applications directly in Python without using GRC — useful for automated scanning, headless operation, and integrating SDR processing into larger applications.

Running a flowgraph from Python

Modifying a running flowgraph from Python

One of GNU Radio's most powerful features — you can change block parameters while the flowgraph is running. This is how Gpredict applies Doppler correction: it calls source.set_center_freq(new_freq) on the running flowgraph every second without stopping and restarting the signal chain.

Reading decoded data from Python

Use a ZMQ Pub Sink block in your flowgraph to publish decoded messages. Connect to it from your Python application using PyZMQ to receive and process the decoded data in real time. This is how many GNU Radio-based monitoring systems work — the flowgraph does the signal processing, a Python application handles the higher-level logic.

Out-of-tree modules — extending GNU Radio

Out-of-tree (OOT) modules add new blocks to GNU Radio beyond those in the standard library. The community has created hundreds of OOT modules covering everything from specific satellite decoders to amateur digital modes.

Key OOT modules for ham radio

Installing an OOT module

Finding OOT modules

The GNU Radio community maintains a list of OOT modules at the GNU Radio wiki (wiki.gnuradio.org/index.php/OutOfTreeModules). GitHub is also a good source — search for "gr-" followed by the protocol or technology you are interested in.

Performance optimization

GNU Radio can be CPU-intensive, especially at high sample rates with multiple processing chains running simultaneously.

Use the correct data types

Processing in float or complex float is faster than double precision. Make sure all your blocks use gr_complex (complex float) for SDR processing rather than complex double. Check block data types in GRC — the wire colours show the data type.

Decimation as early as possible

Reduce sample rate as early as practical in the flowgraph. Processing 2.4 Msps through many blocks is much more expensive than decimating to 48 ksps immediately and processing the lower-rate signal. Apply the channel selection filter and decimation right after the hardware source.

VOLK — vector-optimised library

VOLK is included with GNU Radio and provides CPU-optimised implementations of common signal processing operations using SIMD instructions (SSE, AVX). Run the VOLK profiler once to select the best implementation for your specific CPU:

Affinity and scheduling

For real-time SDR work on a busy system, set GNU Radio's process priority: sudo nice -n -15 python3 my_flowgraph.py. This gives the signal processing priority over other processes and reduces audio dropouts and buffer overflows.

GNU Radio vs GQRX vs OpenWebRX

The right tool for each job

• Everyday monitoring — GQRX or OpenWebRX. No reason to use GNU Radio for simply listening.
• Sharing with others / remote access — OpenWebRX. Browser-native, multiple users, easy setup.
• Custom decoder development — GNU Radio. If no existing software decodes what you want, build it here.
• Satellite telemetry — GNU Radio + gr-satellites. The most capable option by far.
• SDR research and education — GNU Radio. Nothing else gives the same level of insight into signal processing.
• Audio piping to existing decoders — GQRX is simpler. GNU Radio gives more control but requires more work.

Troubleshooting common problems

GRC won't launch — import errors

• Check GNU Radio Python path: python3 -c "import gnuradio; print(gnuradio.__version__)"
• If this fails, GNU Radio Python bindings are not installed or not on the Python path
• Set PYTHONPATH: export PYTHONPATH=/usr/local/lib/python3/dist-packages:
• Try reinstalling: sudo apt install --reinstall gnuradio python3-gnuradio

Flowgraph runs but no audio

• Check the Audio Sink sample rate matches the actual output rate from your signal chain
• Add a Throttle block before the Audio Sink if not using real hardware — without it the flowgraph runs faster than real time and overflows the audio buffer
• Check the audio device name in the Audio Sink — try an empty string to use the default device
• Verify signal is reaching the Audio Sink by adding a QT GUI Level Meter block before it

Buffer overflow / underflow messages

• Buffer overflow (O): downstream processing cannot keep up — reduce sample rate or simplify the flowgraph
• Buffer underflow (U): audio buffer runs dry — increase the audio buffer size or reduce CPU load
• Run the VOLK profiler to optimise signal processing: volk_profile
• Close other CPU-intensive applications while running GNU Radio

RTL-SDR source not found in GRC

• Verify gr-osmosdr is installed: python3 -c "import osmosdr"
• Check DVB-T driver blacklist: cat /etc/modprobe.d/blacklist-rtl.conf
• Test the dongle: rtl_test -t
• Add user to plugdev group: sudo usermod -a -G plugdev

OOT module blocks not appearing in GRC

• Rebuild the GRC block cache: grcc -d ~/.grc_gnuradio
• Check the module installed to the correct prefix: the cmake prefix must match where GNU Radio is installed
• Run ldconfig after installing: sudo ldconfig
• Check GRC_BLOCKS_PATH environment variable includes the OOT module path

Frequently asked questions

Related tools