GQRX on Linux — Complete SDR Receiver Setup and Operating Guide

What is GQRX and what can it do

GQRX is an open-source SDR receiver built on top of GNU Radio and the Qt framework. Written by Alexandru Csete OZ9AEC, it provides a real-time spectrum display, waterfall, and audio demodulation for a wide range of SDR hardware. Unlike OpenWebRX which runs as a server in a browser, GQRX is a traditional desktop application — it runs on the machine with the SDR hardware attached and you operate it directly.

The application sits in the sweet spot between the raw power of GNU Radio Companion (which requires signal processing knowledge) and the simplicity of browser-based receivers. GQRX gives you a proper graphical SDR receiver with full control over all demodulation parameters, without needing to build your own signal processing flowgraph.

What GQRX can do

• Real-time waterfall and spectrum — see signal activity across the entire SDR bandwidth simultaneously
• AM, FM, SSB, CW demodulation — receive voice, broadcast, and amateur radio signals
• Wide frequency coverage — from LF to microwave depending on hardware
• Bookmarks — save favourite frequencies with labels and modes
• Remote control — Hamlib-compatible TCP server for external control
• Audio piping — route demodulated audio to other applications via PulseAudio or virtual audio cables
• I/Q recording and playback — record raw SDR samples for later analysis
• Multiple hardware backends — RTL-SDR, HackRF, Airspy, SDRplay, USRP, and more

Supported SDR hardware

Installation on Ubuntu and Debian

Ubuntu 22.04 and 24.04

This installs GQRX along with all required dependencies including GNU Radio, the RTL-SDR libraries, and Qt5 runtime libraries.

Install additional SDR hardware support

Blacklist the DVB-T driver for RTL-SDR

Build the latest GQRX from source

The repository version may lag the latest release. Build from source for current features and bug fixes:

Raspberry Pi

GQRX runs on Raspberry Pi 4 via the standard apt install. Performance on a Pi 4 is adequate for monitoring but the waterfall refresh rate is lower than on a desktop machine. A Pi 3B+ is marginal — use OpenWebRX instead for Raspberry Pi deployments where remote browser access is acceptable.

Verify installation

First launch and device configuration

On first launch GQRX opens a device configuration dialog. Select your SDR hardware and configure the basic settings before the main window opens.

Device configuration dialog

1. In the Device dropdown select your hardware — for RTL-SDR select "Realtek RTL2838UHIDIR" or similar
2. If your device does not appear click the refresh button next to the dropdown
3. Set the Input rate — 2400000 (2.4 Msps) is a good default for RTL-SDR
4. Set the Decimation to None initially
5. Click OK to open the main window

Device string format

GQRX uses a device string to identify hardware. For RTL-SDR the string is typically rtl=0 for the first dongle. You can also pass additional parameters in the device string:

Saving device configuration

GQRX saves the last used device configuration automatically. To change it later go to File → I/O Devices or press Ctrl+I.

RTL-SDR setup in GQRX

Gain settings

RTL-SDR gain is set in the right panel of GQRX under Input Controls. The gain slider controls the RTL2832 tuner gain in dB. Start with gain in the middle range (around 30–40 dB) and adjust based on what you are receiving:

• Too low — signals are buried in the noise floor, waterfall looks dark and flat
• Too high — strong local signals cause intermodulation and overloading, the waterfall looks washed out and noisy everywhere
• Correct — signals stand out clearly against a consistent noise floor

Enable AGC (Automatic Gain Control) for a quick starting point — GQRX adjusts gain automatically. For best performance set gain manually once you know your local RF environment.

PPM correction

Set the frequency correction in PPM in the Input Controls panel. Most RTL-SDR dongles need between -50 and +50 PPM correction. RTL-SDR Blog v3/v4 are typically within 1–2 PPM. A wrong PPM value causes signals to appear at slightly wrong frequencies.

Direct sampling for HF reception

RTL-SDR dongles can receive HF (below 30 MHz) using direct sampling mode. In the GQRX device string add ,direct_samp=2 for the Q branch (most HF antennas) or ,direct_samp=1 for the I branch:

With direct sampling enabled tune to HF frequencies normally. Signal quality is limited compared to a dedicated HF SDR but perfectly adequate for monitoring amateur bands and shortwave broadcasts.

Bias-T for active antennas

The RTL-SDR Blog v3 and v4 include a software-controlled bias-T that can power active antennas via the coax. Enable it in the device string:

Understanding the GQRX interface

Main window layout

• Spectrum display (top) — shows signal power vs frequency for the current moment, updated continuously
• Waterfall display (bottom) — shows spectrum history scrolling downward, time on the vertical axis
• VFO control (top left) — enter the receive frequency directly, use mouse wheel to tune
• Receiver Options (right panel) — mode selection, filter bandwidth, squelch, and audio gain
• Input Controls (right panel) — hardware gain, PPM correction, and sample rate
• FFT Settings (right panel) — waterfall speed, colour scheme, and display range

Tuning methods

• Click on waterfall or spectrum — tunes to that frequency
• Mouse wheel on VFO display — fine tune in 1 Hz, 10 Hz, or 100 Hz steps depending on where you scroll
• Type directly in VFO field — enter frequency in Hz
• Bookmarks — click a saved bookmark to jump to a stored frequency and mode
• Keyboard arrows — step up/down in frequency

Waterfall controls

The waterfall colour scheme and speed are adjusted in the FFT Settings panel:

• FFT size — larger FFT gives better frequency resolution but slower updates. 32768 is a good balance
• Rate — waterfall scroll speed. Higher rates give a faster moving display
• dB range and reference — adjust these to position the noise floor near the bottom of the colour scale
• Colour scheme — Gqrx, Plasma, and several others available

Demodulation modes — AM, FM, SSB, CW

Filter bandwidth adjustment

The filter bandwidth is shown as a shaded region on the waterfall. Drag the edges of this region to widen or narrow the filter. For SSB voice use 2.4–3.0 kHz, for CW use 200–500 Hz, for AM use 8–12 kHz depending on signal quality. A narrower filter reduces adjacent channel interference but also cuts audio bandwidth.

Squelch

The squelch slider in the Receiver Options panel mutes audio when signal level drops below the threshold. For monitoring a quiet frequency set squelch just above the noise floor. Right-click the squelch slider to reset it to -150 dBFS (effectively off) for always-on monitoring.

AGC (Automatic Gain Control)

AGC in GQRX refers to audio-level AGC — it automatically adjusts the audio output volume to keep voice signals at a consistent level regardless of the received signal strength. Enable it under Receiver Options → AGC. It is helpful for monitoring a frequency where signal strengths vary widely. For digital mode decoding disable AGC to keep audio levels consistent for the decoder.

Operating guide — monitoring and scanning

Monitoring an amateur repeater

1. Set frequency to the repeater output frequency
2. Select FM-N (narrowband FM) mode
3. Set filter bandwidth to 12.5 kHz
4. Adjust squelch just above the noise floor — the audio should be silent until the repeater opens
5. Use bookmarks to save the repeater frequency with its callsign as the label

Monitoring HF amateur bands

1. Enable direct sampling mode if using RTL-SDR for HF
2. Tune to the band you want — e.g. 14.000 MHz for 20m
3. Select USB for frequencies above 10 MHz, LSB below
4. Set filter bandwidth to 2.4 kHz for voice, 500 Hz for CW
5. The waterfall shows all activity across the bandwidth simultaneously — signals appear as vertical lines
6. Click on any signal to tune to it and hear the audio

Using bookmarks for quick band changes

GQRX has a powerful bookmark system. Save your favourite frequencies via Bookmarks → Add bookmark. Each bookmark stores the frequency, mode, bandwidth, and a label. Right-click on the waterfall for a quick-add option. Bookmarks appear in the Bookmarks panel and as markers on the waterfall display.

Scanning for activity

GQRX does not have a built-in scanner but you can scan manually by watching the waterfall while slowly scrolling through a band. The waterfall shows signal history — active frequencies are immediately visible as bright vertical streaks. For automated scanning use a companion application like gpredict or write a simple Python script using GQRX's remote control interface.

Recording I/Q data

Record raw SDR samples for later analysis via File → Start I/Q recording. The recording captures the full SDR bandwidth — you can play it back in GQRX later and tune to any frequency within the recorded bandwidth as if it were live. I/Q files are large — a 2.4 Msps recording at 8-bit depth fills about 300 MB per minute.

Monitoring aircraft with ADS-B

RTL-SDR covers 1090 MHz where aircraft ADS-B transponders broadcast. Tune GQRX to 1090 MHz and switch to AM mode — you will see the ADS-B burst signals as short bright marks on the waterfall. To decode aircraft positions use dump1090 or readsb alongside GQRX rather than trying to decode visually.

Audio output and piping to other programs

GQRX can route its demodulated audio to other applications — this is how you use GQRX as the receive front-end for digital mode decoders like Fldigi, WSJT-X, or Direwolf.

Audio output options

Configure audio output in File → I/O Devices → Audio output or in the Audio tab of the device configuration dialog:

• Default audio device — plays through your speakers or headphones
• UDP audio streaming — streams audio as UDP packets to localhost:7355 for other applications
• PulseAudio virtual sink — route audio to a virtual device that other applications can read

Piping GQRX audio to Fldigi

The most common use case — use GQRX to tune and demodulate, feed the audio to Fldigi for digital mode decoding:

In GQRX set the audio output to the virtual sink. In Fldigi set the audio input to the monitor source of the same sink. Audio flows from GQRX through the virtual sink to Fldigi automatically.

UDP audio for external decoders

GQRX can stream demodulated audio as UDP packets to localhost port 7355. Many SDR companion programs support this natively — check your decoder's documentation for UDP audio input support.

Piping GQRX to Direwolf for APRS

Tune GQRX to 144.390 MHz FM and pipe the audio to Direwolf for APRS packet decoding. Use a PulseAudio virtual sink as described above, then configure Direwolf to use the monitor source of that sink as its audio input. This gives you a full APRS receive station using GQRX for the SDR front-end and Direwolf for packet decoding.

Remote control via Hamlib and rigctld

GQRX has a built-in remote control server compatible with the Hamlib protocol. This allows other applications to control GQRX's frequency and mode as if it were a radio transceiver.

Enabling remote control

1. Go to Tools → Remote control settings
2. Enable Listen on port — default is 7356
3. Click OK — GQRX starts listening for Hamlib commands on that port

Connecting Hamlib to GQRX

Using GQRX with Gpredict for satellite tracking

Gpredict is a satellite tracking application that can control GQRX via the remote control port. Gpredict automatically adjusts GQRX's receive frequency to compensate for Doppler shift as a satellite passes overhead — essential for clean satellite audio reception.

1. Enable GQRX remote control on port 7356
2. In Gpredict go to Edit → Preferences → Interfaces and add a radio interface pointing to localhost:7356
3. In the Gpredict satellite tracking window, click the radio button to enable Doppler correction
4. As the satellite passes, Gpredict sends frequency updates to GQRX in real time

Using GQRX with digital mode software

GQRX + Fldigi for PSK31 and RTTY

Tune GQRX to the digital mode frequency in USB mode, pipe audio to Fldigi via PulseAudio virtual sink, and Fldigi handles the decoding. The key settings:

• GQRX mode: USB
• GQRX bandwidth: 3 kHz or wider to capture the full passband
• GQRX AGC: OFF — Fldigi needs consistent audio levels for decoding
• GQRX audio output: virtual sink
• Fldigi audio input: monitor source of the same virtual sink

GQRX + WSJT-X for FT8

WSJT-X can receive audio from GQRX via a PulseAudio virtual sink. Tune GQRX to 14.074 MHz USB and pipe audio to WSJT-X's audio input. Note that WSJT-X cannot transmit through GQRX — you still need a transceiver for transmitting. This setup is useful for receive-only FT8 monitoring or for evaluating propagation before transmitting.

GQRX + Direwolf for APRS decode

Tune GQRX to 144.390 MHz FM and pipe audio to Direwolf. This creates a software-only APRS receive station with no dedicated hardware TNC. Direwolf can run as an iGate, forwarding decoded packets to APRS-IS. See the Direwolf guide for iGate configuration details.

GQRX + multimon-ng for pager and utility decoding

Hardware compatibility

GQRX vs OpenWebRX vs SDR#

Choosing between GQRX and OpenWebRX

Use GQRX when you are sitting at the machine with the SDR attached and want full desktop control — proper waterfall, audio piping to other applications, I/Q recording, and satellite Doppler correction. Use OpenWebRX when you want to share the receiver with other operators, access it from a phone or tablet, or run it headlessly on a Raspberry Pi as a permanent monitoring station.

Many operators run both — OpenWebRX as a permanent background service for remote monitoring and sharing, and GQRX when they want to do serious local SDR work with audio piping to Fldigi or other decoders.

Troubleshooting common problems

No device found — GQRX shows empty device list

• Check that the DVB-T driver is blacklisted: cat /etc/modprobe.d/blacklist-rtl.conf
• Unplug and replug the SDR dongle
• Test with rtl_test: rtl_test -t
• Check USB permissions — try running GQRX as root once to verify it is not a permissions issue: sudo gqrx
• Add udev rule for non-root access: create /etc/udev/rules.d/rtl-sdr.rules with SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", GROUP="plugdev", MODE="0666"

GQRX starts but waterfall is flat — no signals visible

• Check the gain slider — too low means signals are below the display threshold. Try setting gain to 40 dB as a starting point
• Check the dB range in FFT Settings — the display range may not include your noise floor
• Verify the antenna is connected
• Try a known strong signal — FM broadcast at 88–108 MHz should be visible on any RTL-SDR
• Check that the correct device is selected

Audio is choppy or cutting out

• Increase the audio buffer size in File → I/O Devices → Audio output
• Reduce the sample rate — try 1.8 Msps instead of 2.4 Msps
• Close other CPU-intensive applications
• On Raspberry Pi check for CPU throttling: vcgencmd get_throttled
• Try a different USB port — USB 3.0 interference can cause RTL-SDR dropouts

Frequency is off — signals appear at wrong frequencies

• Set PPM correction in Input Controls — start with 0 and adjust until a known frequency (FM broadcast, NOAA weather) aligns correctly
• Use a GPS-locked reference for precision PPM calibration if needed
• Temperature affects RTL-SDR crystal drift — let the dongle warm up for 5–10 minutes before calibrating

GQRX crashes on startup

• Delete GQRX configuration and start fresh: rm -rf ~/.config/gqrx
• Run from terminal to see error output: gqrx
• Check for conflicting GNU Radio versions: gnuradio-config-info --version
• Try a fresh build from source if the apt version has conflicts

No audio output — waterfall works but no sound

• Check that squelch is not set too high — lower it below the noise floor
• Verify the audio output device in File → I/O Devices
• Check system volume mixer — GQRX may be muted in the mixer
• Try changing the audio output device — some systems default to HDMI audio

Frequently asked questions

Related tools