JTDX on Linux — Complete FT8 Setup, Operating and Troubleshooting Guide

What is JTDX and how does it differ from WSJT-X

JTDX was developed by Igor Chernikov UA3DJY as an enhanced version of WSJT-X, specifically optimized for FT8 and JT65 decoding performance. While WSJT-X is the official reference implementation maintained by the mode's creators, JTDX has developed a loyal following among DX operators who find it decodes more stations — especially weak ones — than WSJT-X in identical conditions.

The core improvement is in the decoder algorithm. JTDX runs multiple decoding passes on each 15-second FT8 window. After the first pass successfully decodes strong signals, subsequent passes subtract those decoded signals from the audio and attempt to decode previously masked weaker signals. This iterative subtraction approach — sometimes called successive interference cancellation — can reveal callsigns that WSJT-X never sees.

In practical terms on a busy band like 20m during peak hours, JTDX typically decodes 5–15% more stations per cycle than WSJT-X. On marginal propagation paths the difference can be more significant — stations that WSJT-X misses entirely may decode cleanly in JTDX.

Installation on Linux

JTDX is not in the standard Linux repositories — it must be downloaded directly from the JTDX project page on SourceForge.

AppImage installation (recommended — works on any Linux distro)

The AppImage is entirely self-contained — no installation, no dependencies to satisfy, no conflicts with WSJT-X. Move it to a convenient location like your home directory and create a desktop shortcut if desired.

Debian / Ubuntu .deb package

Raspberry Pi

JTDX provides armhf AppImages for Raspberry Pi. Download the arm version from the SourceForge project page and make it executable the same way as the x86_64 version. Runs well on Raspberry Pi 3 and 4.

Keeping WSJT-X and JTDX installed simultaneously

Both can be installed at the same time with no conflicts — they store their configuration in separate directories (~/.config/JTDX/ vs ~/.config/WSJT-X/) and separate log files. The only constraint is they cannot use the same audio device simultaneously — close one before opening the other, or use separate audio interfaces.

Configuration — audio, rig control, and station settings

JTDX configuration is nearly identical to WSJT-X — the same settings panels, same options, same structure. If you already have WSJT-X working the transition to JTDX takes under 5 minutes.

Audio setup

Go to File → Settings → Audio and select your audio interface for Input and Output. Use the same device you use for WSJT-X. JTDX works with all the same audio interfaces — USB audio from radios like the IC-7300, Signalink USB, and any standard USB audio adapter.

Rig control

Configure under File → Settings → Radio. Same Hamlib models and serial port settings as WSJT-X. If you use Flrig as a rig control broker, JTDX connects to it on the same port (12345) as WSJT-X.

Station information

Enter under File → Settings → General:

• My Call — your callsign exactly as you want it transmitted
• My Grid — your 4 or 6 character Maidenhead grid square
• IARU Region — Region 1 (Europe/Africa/Middle East), 2 (Americas), or 3 (Asia/Pacific)

Time synchronization

Like WSJT-X, JTDX requires your system clock to be accurate to within 1 second of UTC. Install chrony if not already running:

Rig settings for popular radios

Enhanced decoding — how it works and how to use it

JTDX's decoder is its key differentiator. Understanding how it works helps you get the most out of it.

How the iterative decoder works

Standard FT8 decoding attempts to decode all signals in a 15-second window in a single pass. JTDX adds additional passes:

1. Pass 1 — decodes all signals above a standard threshold
2. Pass 2 — subtracts successfully decoded signals from the audio, then attempts to decode signals that were previously masked by stronger ones
3. Pass 3+ — in aggressive mode, additional passes using different algorithms attempt to decode remaining signals

This approach is most effective on crowded bands where strong signals from nearby stations are masking weaker DX signals underneath them. Removing the strong signals in pass 2 allows JTDX to decode the weaker station that was hidden beneath.

Enabling aggressive decoding

Go to Decode → Aggressive to enable additional decoding passes. This uses more CPU but on any modern machine the difference is imperceptible. Enable it when:

• Chasing weak DX stations at the edge of your propagation path
• Operating on busy bands during peak hours where many strong signals may be masking weaker ones
• Trying to decode a specific station that you can see on the waterfall but JTDX is not decoding

AP (A Priori) decoding

JTDX includes AP (A Priori) decoding — when you are in a QSO with a specific station, JTDX uses knowledge of what messages to expect in the exchange to attempt decoding at lower signal levels than would otherwise be possible. Enable it under Decode → AP. This can make the difference between completing a contact with a station at the very limits of your propagation path.

DX filtering and display

JTDX provides additional filtering options to reduce the Band Activity window clutter on busy bands:

• Show only CQ — hides in-progress QSOs and replies, shows only stations calling CQ
• New DXCC highlight — highlights stations from countries not yet in your log in a distinct color
• New grid highlight — highlights stations in grid squares you have not yet worked
• Continent filter — show only stations from specific continents

JTDX interface guide

The JTDX interface is nearly identical to WSJT-X with a few additions. Anyone familiar with WSJT-X will feel immediately at home.

Band Activity window

Shows all decoded stations from the current 15-second window. Columns show UTC time, signal strength in dB, DT (time offset from your clock), frequency offset in Hz, and the decoded message. Color coding in JTDX:

• Green — stations calling CQ
• Red — stations responding to you
• Yellow — new DXCC entity (when highlight is enabled)
• Cyan — new grid square (when highlight is enabled)
• White — other traffic

Decode count indicator

JTDX shows the number of stations decoded in each window in the status bar. On a busy 20m afternoon you should see 80–150 decodes per window. Significantly fewer may indicate an audio or clock problem. The decode count is useful for comparing JTDX and WSJT-X performance in identical conditions.

Waterfall controls

The waterfall in JTDX has the same controls as WSJT-X — scroll the gain and zero sliders to optimize the display for your noise floor. Signals should appear as clear diagonal stripes against the background. If the waterfall looks washed out or too dark adjust these sliders.

Operating guide — FT8 and JT65 contacts

Making FT8 contacts in JTDX

The FT8 operating procedure in JTDX is identical to WSJT-X — the difference is in what you can decode, not how you operate:

1. Select Mode → FT8 and tune to the FT8 frequency for your chosen band
2. Click Monitor — decoded callsigns appear every 15 seconds
3. Double-click any callsign in green (calling CQ) to initiate a contact
4. Click Enable Tx — JTDX handles the exchange automatically
5. The contact logs when the 73 message is exchanged

Using JTDX for JT65 EME

JT65 was originally designed for Earth-Moon-Earth (moonbounce) communication and JTDX's enhanced JT65 decoding makes it particularly valuable for EME operators. Set up for JT65 EME:

1. Select Mode → JT65
2. Tune to the 2m EME calling frequency — 144.120 MHz is the standard
3. Enable Decode → Aggressive — essential for EME signal levels
4. Enable AP decoding — helps complete contacts at the very limits of the path
5. EME contacts use 60-second periods — be patient, each exchange takes several minutes

Monitoring decode performance

Watch the decode count in the status bar over several cycles. On 20m during a busy afternoon:

• 100+ decodes — excellent, audio and clock are working well
• 50–100 decodes — good, possibly some audio level or noise issue
• Under 50 decodes — check audio levels and clock sync
• 0 decodes with active waterfall — clock is out of sync, fix immediately

Switching efficiently between JTDX and WSJT-X

Many operators use both programs and switch based on the task. A smooth switching workflow:

1. Click Stop in the current program to stop transmitting and receiving
2. Close the program — it saves configuration automatically
3. Open the other program — it reads from its own separate configuration
4. Click Monitor and resume operating

The switch takes under 30 seconds once you are comfortable with both programs. Your log files are separate but both export standard ADIF so contacts from either program import cleanly into CQRLog.

DX chasing with JTDX

DX chasing is where JTDX's enhanced decoder delivers the most noticeable benefit. Here is how to maximize your success working rare stations.

Finding rare DX on the band

When a rare station comes on the air it appears on DX cluster spots quickly. In JTDX enable the New DXCC highlight — stations from countries not in your log appear in yellow in the Band Activity window. This makes new countries immediately visible without having to mentally filter the decode window.

Working a pileup with JTDX

• Watch several cycles to identify the DX station's transmit frequency and their listening range
• Set your transmit frequency within their listening range — not where the main crowd is calling
• Enable aggressive decoding to maximize your chances of decoding their reply to you
• Enable AP decoding once you have initiated a QSO — it helps decode their responses at marginal signal levels
• Be patient — move your frequency slightly if you get no response after 5–6 cycles
• If the DX station is using directional calls ("CQ EU", "CQ NA") respect them and wait if you are not in the target region

Comparing decode rates with WSJT-X

To objectively compare JTDX and WSJT-X performance, run both simultaneously using separate audio interfaces connected to the same radio (via a splitter or the radio's dual audio outputs if available). Note the decode counts in each program over 10–15 cycles on a busy band. Most operators find JTDX decodes more stations, particularly at the lower signal levels where the iterative decoder provides the most benefit.

When JTDX gives the edge

JTDX vs WSJT-X — detailed comparison

Which should you use

The honest answer is: use both. Install WSJT-X for contesting (FT4), WSPR beaconing, and meteor scatter (MSK144). Use JTDX for everyday FT8 DX chasing and JT65 EME. The programs coexist perfectly and switching between them is fast. If you only want one program and primarily do FT8 on HF, JTDX's better decoder gives it the edge for that specific use case.

Logging and LoTW integration

JTDX logs contacts to ~/.local/share/JTDX/jtdx_log.adi in standard ADIF format. This file works with any ADIF-compatible logging application.

LoTW upload from JTDX

JTDX supports the same TQSL-based LoTW upload as WSJT-X. Configure it under File → Settings → Reporting — same procedure as WSJT-X. Enter your TQSL path, callsign, and certificate, then enable automatic upload after each contact.

CQRLog integration

Point CQRLog at the JTDX ADIF log file under Settings → Log → WSJT-X/JTDX log file. CQRLog monitors it for new contacts and imports them automatically. Note that CQRLog labels this setting as WSJT-X but it works equally well with the JTDX log file.

Merging JTDX and WSJT-X logs

If you use both programs, import both ADIF files into CQRLog to keep a single complete log. CQRLog handles duplicate detection — contacts that appear in both files (if you somehow made the same contact in both programs) are identified and skipped.

PSKReporter

JTDX automatically reports received stations to PSKReporter.info. Enable it under File → Settings → Reporting → Enable PSKReporter spotting. Your reception reports appear on the world map within minutes — useful for checking propagation without making contacts.

Troubleshooting common problems

JTDX won't launch — missing libraries

• The AppImage is self-contained and should not have library issues — if it fails to launch try making it executable again: chmod +x jtdx-*.AppImage
• Try running from a terminal to see error output: ./jtdx-*.AppImage
• On some systems FUSE is required for AppImages: sudo apt install fuse libfuse2
• For the .deb version check for missing dependencies: sudo apt install --fix-broken

Nothing decoding in JTDX

• Clock sync first — same requirement as WSJT-X. Run chronyc tracking and check the offset. Force sync with sudo chronyc makestep
• Verify audio device selection in File → Settings → Audio
• Check that you are on the correct FT8 frequency — 14.074 MHz USB for 20m
• Verify the radio is in USB or USB-D mode, not FM or AM
• Check the DT column values — if all DT values are similar and non-zero your clock needs adjustment

JTDX decodes fewer stations than WSJT-X

This occasionally happens and is counterintuitive given JTDX's reputation. Common causes:

• Aggressive decoding is not enabled — turn it on under Decode → Aggressive
• Clock offset differs slightly between the two programs — recalibrate chrony
• Audio levels are slightly different between sessions — check the waterfall and adjust gain
• JTDX version is old — update to the latest release from SourceForge

Rig control not working

• Check dialout group membership: groups | grep dialout
• Verify the serial port: ls /dev/ttyUSB*
• Check baud rate matches radio setting exactly
• Make sure WSJT-X is not also running and holding the serial port

JTDX crashes on startup

• Delete the JTDX configuration: rm -rf ~/.config/JTDX
• Try a fresh AppImage download — the file may be corrupted
• Run from terminal to see the crash output
• Check available disk space: df -h ~

Frequently asked questions

Related tools