WSJT-X on Linux — Complete FT8 Setup and Operating Guide

What is WSJT-X and why use it

WSJT-X was developed by Nobel Prize winner Joe Taylor K1JT along with Steve Franke K9AN and Bill Somerville G4WJS. The software implements a family of digital protocols specifically designed for weak-signal communication — FT8 can decode signals that are 15 dB below the noise floor, meaning you can make contacts when the band sounds completely dead to SSB.

FT8 has become the most popular HF digital mode in amateur radio history. On 20 meters the FT8 frequency at 14.074 MHz is active 24 hours a day with thousands of stations worldwide. A 5-watt station with a wire antenna can work over 100 countries on FT8 during a single solar cycle — results that would require hundreds of watts and a beam antenna on SSB.

WSJT-X handles everything automatically — timing, encoding, decoding, sequencing, and logging. Your job as the operator is to select which stations to call and when. The software handles the actual exchange.

Installation on Ubuntu and Debian

Ubuntu 22.04 and 24.04

Install the latest version directly

The repository version may be behind the current release. Download the latest .deb package from the WSJT-X SourceForge page and install it directly:

The apt install method automatically resolves all dependencies including Hamlib and Qt libraries.

Raspberry Pi OS

WSJT-X runs well on Raspberry Pi 3 and 4. Use the standard apt install — the armhf and arm64 packages are in the Raspberry Pi OS repositories. On a Raspberry Pi 4 with a USB audio interface and inexpensive radio you have a complete FT8 station that runs 24/7 on minimal power.

Verify the installation

Sound card and PTT setup

Audio setup for WSJT-X is similar to Fldigi but with one critical additional requirement — precise timing. FT8 uses 15-second transmission windows that must be synchronized to UTC within 1 second.

Audio interface options

• Radio's built-in USB audio — best option for modern radios. The IC-7300, IC-7610, FTDX-10, FT-991A, and TS-890S all present as USB audio devices on Linux. One USB cable handles both audio and CAT control.
• Dedicated USB audio interface — Signalink USB, Masters Communications DRA series. Optical isolation eliminates ground loop problems.
• Built-in sound card — works but prone to ground loop hum. Use line-in, not microphone input.

Configuring audio in WSJT-X

Go to File → Settings → Audio and configure:

• Input — select your radio's USB audio device or external interface
• Output — same device as input
• Channels — Mono for most setups

PTT control options

Audio levels for clean FT8 transmission

Correct audio levels are critical. Overdriving causes splatter that interferes with other stations on adjacent frequencies:

• Set your radio to USB or USB-D (data) mode
• Disable all speech processing and compression on the radio
• Key up on a clear frequency and check the ALC — it should show zero or minimal deflection
• The WSJT-X power level slider controls transmit audio — start at 25% and increase slowly until ALC is just at zero
• Check your signal on the PSKReporter map after a few transmissions to verify it is clean

Rig control for popular radios

Rig control lets WSJT-X set your radio's frequency and mode automatically when you select a band. Configure it under File → Settings → Radio.

Icom IC-7300 setup on Linux

The IC-7300 is the most popular radio for Linux FT8 because its built-in USB audio and CAT control work perfectly on Linux with no drivers needed:

1. Connect the IC-7300 to your computer via USB
2. Linux creates two devices — a USB serial port for CAT and a USB audio device for audio
3. Find the serial port: ls /dev/ttyUSB* — it will be /dev/ttyUSB0 or similar
4. In WSJT-X Settings → Radio: Rig = Icom IC-7300, Serial Port = /dev/ttyUSB0, Baud Rate = 19200
5. In Settings → Audio: Input and Output = IC-7300 USB Audio Codec
6. On the IC-7300: Menu → Set → Connectors → USB SEND/Keying → USB MOD Level = 50%, DATA MOD = USB

Settings for common radios

Serial port permissions

Time synchronization — critical for FT8

FT8 uses strict 15-second transmission windows synchronized to UTC. If your computer clock is off by more than 1–2 seconds you will not decode stations correctly and other stations will not decode you. This is the single most common cause of FT8 problems on Linux.

Install and configure chrony

Verify time accuracy

Check your clock offset in WSJT-X

WSJT-X shows a DT (delta time) value for each decoded station — this is the timing offset between your clock and theirs. If DT values are consistently greater than ±2 seconds your clock is out of sync. Values between -1 and +1 are normal.

Understanding the WSJT-X interface

The waterfall

The waterfall shows the received audio spectrum — frequency on the horizontal axis, time moving downward. FT8 signals appear as short diagonal lines or clusters of lines lasting about 13 seconds. Multiple signals are visible simultaneously across the 3 kHz audio passband. The waterfall updates every 15 seconds in sync with the FT8 timing cycle.

Band Activity window

The Band Activity window on the left shows all decoded stations from the current 15-second window. Each line shows UTC time, signal strength in dB (negative numbers are below the noise floor), DT (time offset), frequency offset in Hz, and the decoded message. Color coding indicates status — green for stations calling CQ, red for stations responding to you, white for other traffic.

Rx Frequency window

The Rx Frequency window on the right shows only stations responding to your CQ or stations you are calling. This is where your active QSO progress appears — watch it during a contact to see the exchange proceeding automatically.

Message generation panel

The bottom panel shows the messages WSJT-X will transmit during an exchange. These are generated automatically based on the contact in progress — you don't need to type anything during a normal FT8 QSO. The Tx 1 through Tx 6 buttons show each stage of the exchange sequence.

Modes — FT8, FT4, JT9, WSPR explained

Operating guide — making FT8 contacts

Your first FT8 contact — step by step

1. Set your radio to USB or USB-D mode and tune to 14.074 MHz
2. In WSJT-X select Mode → FT8
3. Click Monitor — callsigns start appearing in the Band Activity window every 15 seconds
4. Enter your callsign, grid square, and power under File → Settings → General if not already done
5. Double-click any callsign showing CQ in green — WSJT-X generates your reply and queues it for the next transmission window
6. Click Enable Tx — WSJT-X transmits your reply automatically at the correct moment
7. Watch the Rx Frequency window — the exchange proceeds automatically through signal report, RRR confirmation, and 73
8. The contact logs automatically when the 73 message is received or sent

Understanding the FT8 timing cycle

FT8 operates in strict alternating 15-second windows. One group of stations transmits during even seconds (0–15, 30–45) and the other during odd seconds (15–30, 45–60). When you answer a CQ WSJT-X automatically selects the opposite slot from the station you are calling. You never need to manually manage timing — the software handles it, but understanding it helps when troubleshooting.

Calling CQ

To generate contacts rather than answer CQs, click Enable Tx then select the CQ message in the Tx panel. WSJT-X transmits "CQ [YOURCALL] [YOURGRIDSQUARE]" and handles any responses automatically. Many stations leave CQ running for hours, accumulating contacts while doing other things.

Reading signal reports

FT8 signal reports are in dB relative to noise — not the traditional RST system. Common values and what they mean:

FT8 frequencies by band

DX chasing and pileup operating

FT8 has transformed DX operating. Rare stations that previously required perfect conditions and a kilowatt are now workable with modest equipment. Here is how to maximize your success working DX on FT8.

Spotting networks

When a rare DX station comes on the air it appears on DX cluster spots almost immediately. PSKReporter (pskreporter.info) shows where the station is being heard in real time. Check both before tuning — if the DX station is not being heard in your region the propagation path is not open yet.

Working a DX pileup

• Find the DX station's transmit frequency in the Band Activity window — watch several cycles to identify it
• The DX station typically listens on a range of frequencies above or below their transmit frequency
• Set your transmit frequency to a point within their listening range — not on top of where everyone else is calling
• Enable Tx and be patient — the DX station's software works through callers methodically
• Do not call continuously on the same frequency if you get no response after several cycles — move slightly
• Watch for "CQ DX" or directional calls like "CQ EU" — if they are calling a specific region and you are not in it, wait

Fox and Hound mode

During major DX expeditions WSJT-X uses a special Fox and Hound (F/H) mode that allows the DX station to work many stations simultaneously. The DX station (Fox) transmits on one frequency while callers (Hounds) spread across a range of frequencies. Enable Hound mode under Mode → FT8 when a DX expedition announces F/H operation — your WSJT-X will automatically behave as a Hound.

Using PSKReporter to check propagation

PSKReporter at pskreporter.info shows a real-time map of which stations are receiving you and which stations you are receiving. After transmitting for a few cycles check your callsign on PSKReporter to see where your signal is reaching. This is invaluable for understanding propagation and deciding which bands to use for specific DX targets.

WSPR propagation beaconing

WSPR (Weak Signal Propagation Reporter) is a beacon mode that transmits a 2-minute message containing your callsign, grid square, and power level at extremely low signal levels (-31 dB sensitivity). Receiving stations upload spots to wsprnet.org where you can see a live world map of where your signal is being heard.

Setting up WSPR

1. Select Mode → WSPR in WSJT-X
2. Tune to the WSPR frequency for your chosen band — 14.097 MHz is the most active on 20m
3. Set your transmit percentage to 20% or less — WSPR is primarily a receive mode
4. Enable Upload spots to contribute your received spots to wsprnet.org
5. Click Monitor and let it run — spots from stations worldwide appear every 2 minutes

WSPR frequencies

Logging and LoTW upload

WSJT-X logs all completed contacts to an ADIF file at ~/.local/share/WSJT-X/wsjtx_log.adi. It can also upload to LoTW automatically and report to PSKReporter in real time.

LoTW automatic upload setup

1. Install TQSL: sudo apt install tqsl
2. Open TQSL and download your LoTW certificate — you need a certificate for each callsign and location you operate from
3. In WSJT-X go to File → Settings → Reporting
4. Enable Upload QSOs to LoTW
5. Set the path to your TQSL executable — usually /usr/bin/tqsl
6. Enter your LoTW callsign and select your certificate

After each completed contact WSJT-X automatically signs and uploads it to LoTW via TQSL. New confirmations typically appear within minutes.

Manual ADIF export and upload

eQSL upload

Export the ADIF file and upload it manually to eQSL.cc via their web interface, or use CQRLog which handles eQSL uploads automatically when you import the WSJT-X ADIF log.

PSKReporter automatic reporting

WSJT-X automatically reports both transmitted and received stations to PSKReporter. Enable it under File → Settings → Reporting → Enable PSKReporter spotting. Your reception reports appear on the PSKReporter map within minutes of receiving a signal — useful for checking propagation without making a contact.

Hardware compatibility

Radios with built-in USB audio — no external interface needed

External USB audio interfaces

Integration with CQRLog and GridTracker

CQRLog integration

CQRLog can monitor WSJT-X's log file and import new contacts as they are logged. Set the WSJT-X ADIF log path in CQRLog under Settings → Log → WSJT-X log file. CQRLog checks for new contacts every few seconds and imports them automatically, handling LoTW upload and award tracking in the background.

Alternatively use WSJT-X's UDP logging — enable it under File → Settings → Reporting → UDP Server and point CQRLog at the same UDP port for real-time contact delivery.

GridTracker

GridTracker is a companion application that displays your FT8 contacts on a live world map. It connects to WSJT-X via the UDP broadcast port 2237 and shows every decoded station on a map with their grid square highlighted. Run GridTracker alongside WSJT-X — it connects automatically with no configuration needed.

Running Fldigi and WSJT-X together

Fldigi and WSJT-X cannot share the same audio device simultaneously. Options for running both:

• Use two separate USB audio interfaces — one radio port for each application
• Use a radio with built-in dual USB audio (IC-7610) — one for each application
• Switch between applications — close one before opening the other

Rig control via Flrig can be shared — both Fldigi and WSJT-X can connect to the same Flrig instance for frequency and mode reading, as long as only one transmits at a time.

Troubleshooting — no decodes and common problems

Nothing decoding — waterfall is active but no callsigns appear

This is the most common WSJT-X problem. Work through these checks in order:

1. Check your system clock first — run chronyc tracking and check the System time offset. If it is more than 2 seconds WSJT-X will not decode. Fix with sudo chronyc makestep to force an immediate sync.
2. Verify you are on the correct frequency — FT8 on 20m is 14.074 MHz USB. Many beginners accidentally tune to 14.070 (PSK31 frequency) or forget to set USB mode.
3. Check audio device selection — File → Settings → Audio and verify the correct input device is selected. Run arecord -l to see available devices.
4. Check audio levels — the waterfall should show colored signals. If it is completely dark the receive audio is not reaching WSJT-X. If it is saturated red the level is too high.
5. Verify the mode — select Mode → FT8 and confirm it is selected, not a different mode.

Clock is synchronized but still no decodes

• Check the DT column — if DT values are consistently ±2 or more your clock needs adjustment even if chrony shows it as synchronized
• Try sudo chronyc makestep to force an immediate time correction
• Check if your system is in a virtual machine — VMs often have poor timekeeping. Use sudo apt install open-vm-tools on VMware or similar tools for your hypervisor

Waterfall shows no signals at all

• No audio input reaching WSJT-X — check device selection and audio cable connections
• Wrong audio device selected — run arecord -l and match the device shown to what is selected in WSJT-X settings
• Audio device in use by another application — close Fldigi or any other audio application
• PulseAudio conflict — try selecting the PulseAudio device in WSJT-X instead of the ALSA hardware device directly
• Muted input — open alsamixer, press F4 for capture, and check that your input is not muted

WSJT-X won't key the transmitter

• Check dialout group membership: groups | grep dialout — if dialout is not listed run sudo usermod -a -G dialout and log out/in
• Verify the serial port exists: ls /dev/ttyUSB*
• Check that no other application is using the same serial port
• Try CAT PTT instead of RTS/DTR or vice versa in Settings → Radio → PTT Method
• Verify your radio is in USB or USB-D mode — many radios will not key via CAT when in FM or AM mode

Audio is transmitting but no one decodes my signal

• Check your ALC — any ALC action means you are overdriving and causing splatter. Reduce the transmit audio level
• Verify your clock is accurate — if you are transmitting at the wrong time other stations' decoders will miss you
• Check PSKReporter after a few transmissions — if your signal is not appearing anywhere your audio is not reaching the radio
• Make sure speech processing and compression are disabled on your radio
• Verify you are in USB or USB-D mode, not SSB, FM, or AM

Rig control not working

• Check dialout group: groups | grep dialout
• Verify baud rate matches radio setting exactly — this is the most common rig control failure
• Check the serial port: ls -la /dev/ttyUSB*
• Test Hamlib independently: rigctl -m [model] -r /dev/ttyUSB0 -s [baud] f — should return the current frequency
• Close any other application using the same serial port (Fldigi, CQRLog, Flrig)

WSJT-X crashes or freezes

• Delete the WSJT-X configuration and start fresh: rm -rf ~/.config/WSJT-X
• Check available disk space — WSJT-X writes log files continuously
• Run from a terminal to see error output before the crash: wsjtx
• Update to the latest version — crashes in older versions are often fixed in newer releases

Frequently asked questions

Related tools