Installation Guide
Get It
Running.
Pick your platform below. Windows, Linux, and macOS all ship as ready-to-run apps — no Python needed. Prefer to run from source instead? That's available on every platform too.
Pick your platform below. Windows, Linux, and macOS all ship as ready-to-run apps — no Python needed. Prefer to run from source instead? That's available on every platform too.
Most people want the .exe above. The source download is only useful if you want to read or modify the code — run it with pip3 install -r requirements.txt then python3 launcher.py.
Prefer the terminal? In PowerShell: iwr https://gt7trace.netlify.app/gt7telem-windows.zip -OutFile gt7telem-windows.zip for the .exe, or swap in gt7telem-source.zip for the Python source.
pip install gt7tracetelem installs it as a library too — note the importable module is gt7telem (not gt7tracetelem): import gt7telem, or run gt7telem from the terminal. If you already have an unrelated package that installs a top-level gt7telem module, the two will conflict — check first with pip show gt7telem.winget submission is still in Microsoft's review queue — it'll show up here once approved.Right-click gt7telem-windows.zip → Extract All, then double-click TRACE.exe inside the extracted folder.
A menu pops up with three tools — Live Dashboard, Lap Analyst, and Race Analyst. Pick one to launch it. (The Track Map isn't a separate menu entry — it's a live panel inside the Live Dashboard.) Re-open TRACE.exe any time to switch tools.
Make sure GT7 is open and running on your PS4/PS5 first. In the Dashboard, type your console's IP into the field at the top and hit Enter — it's remembered automatically next time you open TRACE.
Most people want the binary above. Use the source download if your distro/glibc is too old for the prebuilt binary, or if you just want to read the code.
Prefer the terminal? curl -LO https://gt7trace.netlify.app/gt7telem-linux.zip for the binary, or swap in gt7telem-source.zip for the Python source.
pip install gt7tracetelem installs it as a library too — note the importable module is gt7telem (not gt7tracetelem): import gt7telem, or run gt7telem from the terminal. If you already have an unrelated package that installs a top-level gt7telem module, the two will conflict — check first with pip show gt7telem.Extract the zip, open a terminal in that folder, and run:
A menu pops up with three tools — Live Dashboard, Lap Analyst, and Race Analyst. Pick one to launch it. (The Track Map isn't a separate menu entry — it's a live panel inside the Live Dashboard.) Re-run TRACE any time to switch tools.
Make sure GT7 is open and running on your PS4/PS5 first. In the Dashboard, type your console's IP into the field at the top and hit Enter — it's remembered automatically next time you open TRACE.
Most people want the .app above — built automatically on every release via GitHub Actions, no Python required. The source download is only useful if you want to read or modify the code, or you're on an older Intel Mac.
Prefer the terminal? curl -LO https://gt7trace.netlify.app/gt7telem-macos.zip for the .app, or swap in gt7telem-source.zip for the Python source.
pip install gt7tracetelem installs it as a library too — note the importable module is gt7telem (not gt7tracetelem): import gt7telem, or run gt7telem from the terminal. If you already have an unrelated package that installs a top-level gt7telem module, the two will conflict — check first with pip show gt7telem.Unzip, then drag TRACE.app into Applications (or just double-click it from the extracted folder).
xattr -cr /Applications/TRACE.app in Terminal once.A menu pops up with three tools — Live Dashboard, Lap Analyst, and Race Analyst. Pick one to launch it. (The Track Map isn't a separate menu entry — it's a live panel inside the Live Dashboard.) Re-open TRACE.app any time to switch tools.
Make sure GT7 is open and running on your PS4/PS5 first. In the Dashboard, type your console's IP into the field at the top and hit Enter — it's remembered automatically next time you launch it.
Core protocol by
Bornhall — GT7 UDP TelemetryCar & track database by
ddm999 — gt7infocar_ids.csv and course_ids.csv) and reads from it — the lookup itself, and the work of keeping it current as Polyphony adds new content, is entirely ddm999's.Enjoying TRACE?
Support the ProjectThis section is for anyone using the "Python Source" download instead of the ready-to-run app — a full walkthrough assuming nothing is set up yet.
1. Open a terminal in the extracted folder
Windows: unzip the download, open the folder in File Explorer, then right-click inside it (on empty space) → Open in Terminal. If that option isn't there, press Win, type cmd, hit Enter, then type cd followed by a space and drag the folder into the window to fill in the path, then press Enter.
macOS: unzip the download, press Cmd + Space, type Terminal, hit Enter. Type cd followed by a space, then drag the unzipped folder into the Terminal window — it'll fill in the path automatically — and press Enter.
Linux: unzip the download, right-click inside the folder in your file manager → Open Terminal Here (wording varies by desktop environment — GNOME/KDE both have some version of this).
2. Check Python is installed (3.10 or newer)
Run this in the terminal you just opened:
If you see a version number 3.10 or higher, skip to step 3. If you get command not found, 'python' is not recognized, or a version below 3.10, install/update Python first:
Windows / macOS: download the installer from python.org/downloads and run it. On Windows, make sure to tick "Add python.exe to PATH" on the first install screen — easy to miss, and without it the python command won't work afterward.
Linux: sudo apt install python3 python3-pip python3-venv python3-tk (Ubuntu/Debian) or the equivalent for your distro.
Once installed, close and reopen the terminal, then re-run the version check above to confirm it worked.
3. Install the dependencies
This pulls in numpy, pandas, matplotlib, and pycryptodome — takes a minute or two. If you get pip: command not found, your Python install didn't include pip; reinstalling from python.org (not a system package manager) usually fixes it.
4. Run it
A small menu window should pop up with three tools — Live Dashboard, Lap Analyst, and Race Analyst. Pick one to launch it. (The Track Map is a panel inside the Live Dashboard, not a separate menu entry.)
Common errors
ModuleNotFoundError: No module named 'tkinter' — macOS: your Python didn't include it; reinstall via the official python.org installer, not Homebrew. Linux: run sudo apt install python3-tk.
ModuleNotFoundError: No module named 'numpy' (or pandas/matplotlib) — step 3 didn't finish or errored partway through; re-run the pip install command and read the error output.
Nothing happens when you double-click launcher.py directly — that's expected on most systems; run it through the terminal with the command above instead.
Once it's running, your PS4/PS5 IP is entered once in the Dashboard's IP field and saved automatically from then on — no config file editing needed.
RECORD_RATE_OPTIONS = [10, 20, 30, 60] near the top of gt7telem/dashboard.py — any Hz value you add there shows up as a real, working dropdown option next time you launch it. No other config needed.Yes. The telemetry UDP stream is identical on PS4 and PS5. Just set your PS5's IP in the Dashboard the same way.
Yes — there's an optional REC RATE dropdown next to the connection controls in the Live Dashboard (10 / 20 / 30 / 60 Hz). It only affects Record Lap / Record Race; it never invents data between real packets, only thins samples down to whatever rate you pick. Laps and races recorded at different rates still compare correctly against each other in the Lap Analyst and Race Analyst — both go off each sample's actual timestamp, not an assumed fixed interval.
GT7's telemetry doesn't report a track ID the way it does a car ID — there's nothing to auto-detect. So instead of leaving it free-typed (and quietly splitting one track's laps across "suzuka" / "Suzuka Circuit" / "suzuka_circuit" depending on how you typed it that session), it's a searchable picker seeded from ddm999's gt7info course database — 120+ real circuit and layout names, reverse layouts and sub-layouts included. You can still type a name that isn't in the list.
Run add_track.py from the Python source download — it asks for just the track name (no ID needed, since telemetry doesn't expose one to look up) and adds it to your local course_ids.csv. It'll show up in the dropdown next time you open the Dashboard.
Two most common causes: the IP entered in the app is wrong, or your PC and PS4/PS5 are on different subnets (e.g. one on 2.4 GHz, one on 5 GHz). Also make sure GT7 is actually in-game, not just sitting on the PS home screen.
That's expected for an unsigned indie tool — click More info then Run anyway. If your antivirus quarantines it, that's a false positive common with PyInstaller-built apps; you can allowlist the file.
Depends how you installed it. The standalone .exe / .app / binary builds are portable and create a laps folder right next to the executable. pip installs and the Python source download use ~/TRACE/laps instead, so an upgrade can’t wipe them. Either way the Lap Analyst and Race Analyst read from there automatically. To move it somewhere else, edit LAPS_FOLDER in settings.json and restart — there's no in-app setting for the laps folder.
Lap Analyst compares two individual laps in detail — 16 chart groups, sector timing, heat maps. Race Analyst compares two full race sessions side by side, with synced replay and CSV/HTML export.
Load a lap in Lap Analyst, then hit Submit to Leaderboard in the LEADERBOARD sidebar panel. Submitting requires a free account — if you skipped that at first launch, it offers to create one right there (display name only, no email or password). It then asks for the PSN name to show on the row (remembered for next time, editable each submit) and sends your car, track, lap time, and a compact input trace to a shared per-car, per-track leaderboard. The Top-10 panel updates live. Submission is entirely opt-in — nothing goes anywhere unless you press that button. Full breakdown of exactly what's sent on the Privacy page.
Yes — the leaderboard is public by design, so anyone using TRACE can see the Top-10 for a car/track and download a lap as a ghost. Use a PSN name you're fine having attached to that lap time. Physically-impossible times are rejected automatically, and times beating the record by more than 20% get held for manual review before they publish.
Press Load Community Line in the LEADERBOARD panel to pull a community-average speed/throttle/brake line, computed from the current top 10 leaderboard laps for your loaded car and track, and overlay it against your own lap on the Consensus chart tab. Needs at least one other public submission for that car+track to show anything.
Yes — TRACE.app is built automatically on a GitHub-hosted Apple Silicon runner every release, no physical Mac needed on this end. See the macOS tab above. On an older Intel Mac, use the Python source download instead.
The GT7 UDP telemetry stream was reverse-engineered by the community — specifically Bornhall, whose gt7telemetry repo figured out the Salsa20 decryption key and full packet structure. This project's core data layer is built on that work.
GT7's telemetry only reports a numeric car ID, and no track ID at all. Both the car name lookup and the TRACK dropdown's course list are sourced entirely from ddm999's gt7info community database — see the Features page for exactly which parts of the app that powers.