NextTrace, an open source visual route tracking CLI tool
NextTrace
An open source visual routing tool that pursues light weight, developed using Golang.
HomePage: www.nxtrace.org
IAAS Sponsor
We are extremely grateful to DMIT, Misaka and SnapStack for providing the network infrastructure that powers this project.
How To Use
Document Language: English | 简体中文
⚠️ Please note: We welcome PR submissions from the community, but please submit your PRs to the NTrace-dev repository instead of NTrace-core repository.
Regarding the NTrace-dev and NTrace-core repositories:
Both will largely remain consistent with each other. All development work is done within the NTrace-dev repository. The NTrace-dev repository releases new versions first. After running stably for an undetermined period, we will synchronize that version to NTrace-core. This means that the NTrace-dev repository serves as a "beta" or "testing" version.
Please note, there are exceptions to this synchronization. If a version of NTrace-dev encounters a serious bug, NTrace-core will skip that flawed version and synchronize directly to the next version that resolves the issue.
Automated Install
- Debian / Ubuntu
nexttrace-debs APT repository
- Supports: amd64, i386, arm64, armel, armhf, loong64, mipsel, mips64el, ppc64el, riscv64, s390x
- Add the repository and install the default package:
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL -o /tmp/nexttrace-archive-keyring.gpg https://github.com/nxtrace/nexttrace-debs/releases/latest/download/nexttrace-archive-keyring.gpg
sudo install -m 0644 /tmp/nexttrace-archive-keyring.gpg /etc/apt/keyrings/nexttrace.gpg
rm -f /tmp/nexttrace-archive-keyring.gpg
printf '%s\n' 'Types: deb' 'URIs: https://github.com/nxtrace/nexttrace-debs/releases/latest/download/' 'Suites: ./' 'Signed-By: /etc/apt/keyrings/nexttrace.gpg' | sudo tee /etc/apt/sources.list.d/nexttrace.sources >/dev/null
sudo apt update
sudo apt install nexttracesudo apt install nexttrace-tiny
sudo apt install ntrnexttrace, nexttrace-tiny, ntr
- Linux / macOS / BSD
curl -sL https://nxtrace.org/nt | bash- One-click installation script (Tiny)
curl -sL https://nxtrace.org/nt | bash -s -- --flavor tiny- One-click installation script (NTR)
curl -sL https://nxtrace.org/nt | bash -s -- --flavor ntr- Installed command names: Full nexttrace, Tiny nexttrace-tiny, NTR ntr
- Arch Linux AUR installation command - Directly download bin package (only supports amd64)
yay -S nexttrace-binyay -S nexttrace- Linuxbrew's installation command
Same as the macOS Homebrew installation method. The homebrew-core formula provides the Full flavor (nexttrace); the nxtrace/nexttrace tap provides all three flavors.
- deepin installation command
apt install nexttracex env use nexttrace- Termux installation command
pkg install root-repo pkg install nexttraceopkg install nexttrace- macOS
brew install nexttracenxtrace/nexttrace tap version (periodically synced from the latest NTrace-core release)
brew tap nxtrace/nexttrace
brew install nxtrace/nexttrace/nexttrace
brew install nxtrace/nexttrace/nexttrace-tiny
brew install nxtrace/nexttrace/ntr- Windows
winget install nexttrace- Windows Scoop installation command - Scoop-extras version
scoop bucket add extras && scoop install extras/nexttracePlease note:
- The
nexttrace-debsAPT repository is maintained by nxtrace and wcbing. - Other package sources above are maintained by open-source enthusiasts. Availability and timely updates are not guaranteed. If you encounter problems, please contact the repository maintainer to solve them, or use the binary packages provided by the official build of this project.
Manual Install
- Download the precompiled executable
Release provides compiled binary executables for many systems and different architectures. If none are available, you can compile it yourself.
- Some essential dependencies of this project are not fully implemented on Windows by Golang, so currently, NextTrace is in an experimental support phase on the Windows platform.
Build Variants
Starting from this release, NextTrace is published in three flavors under the same tag. Choose the one that best fits your use case:
| Feature | nexttrace (Full) | nexttrace-tiny | ntr | | --------------------- | :----------------: | :--------------: | :----------: | | Normal traceroute | ✅ | ✅ | — | | Standalone MTU (--mtu) | ✅ | ✅ | — | | CDN Speed (--speed) | ✅ | — | — | | IP annotation (--nali) | ✅ | — | — | | MTR TUI | ✅ | — | ✅ (default) | | MTR report (-r) | ✅ | — | ✅ | | MTR wide (-w) | ✅ | — | ✅ | | MTR raw (--raw) | ✅ | — | ✅ | | Globalping (--from) | ✅ | — | — | | WebUI (--deploy) / MCP (--deploy --mcp) | ✅ | — | — | | Fast Trace (-F) | ✅ | ✅ | — | | Default mode | traceroute | traceroute | MTR TUI | | Binary name | nexttrace | nexttrace-tiny | ntr |
Note:APT (nexttrace-debs)and theHomebrew tap (nxtrace/nexttrace)provide all three flavors: Full (nexttrace), Tiny (nexttrace-tiny), and NTR (ntr).homebrew-core, AUR, Scoop, and other package managers currently install the Full (nexttrace) version only.
Feature Matrix
nexttrace— Full-featured build. Includes traceroute, standalone MTU, CDN speed test, IP annotation, MTR, Globalping, Fast Trace, WebUI, and deploy MCP.nexttrace-tiny— Lightweight build. Keeps normal traceroute, standalone MTU, and Fast Trace. No CDN speed test / IP annotation / MTR / Globalping / WebUI / MCP. Suitable for embedded or minimal environments.ntr— MTR-focused build. Runs MTR TUI by default. No normal traceroute mode, standalone--mtu, CDN speed test, IP annotation, Globalping, Fast Trace, WebUI, or MCP.
Manual Build
Build from source with Go 1.22+ installed:
# Full (all features)
go build -trimpath -o dist/nexttrace -ldflags "-w -s" .
Tiny (no MTR, no Globalping, no WebUI)
go build -tags flavor_tiny -trimpath -o dist/nexttrace-tiny -ldflags "-w -s" .
NTR (MTR-only)
go build -tags flavor_ntr -trimpath -o dist/ntr -ldflags "-w -s" .Cross-compile example:
# Linux arm64, Tiny flavor
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
go build -tags flavortiny -trimpath -o dist/nexttrace-tinylinux_arm64 -ldflags "-w -s" .The tiny and ntr flavors use compile-time build tags to exclude modules — this is not a runtime switch. You can verify with go version -m <binary> that gin and globalping-cli are absent from nexttrace-tiny and ntr.
The .cross_compile.sh script supports building flavors:
./.cross_compile.sh all # Build all three flavors for all platforms
./.cross_compile.sh full # Build only nexttrace (Full)
./.cross_compile.sh tiny # Build only nexttrace-tiny
./.cross_compile.sh ntr # Build only ntrRelease Assets Naming
Release binaries follow this naming convention:
{binary}{os}{arch}[v{arm}][.exe][_softfloat]Examples:
nexttracelinuxamd64,nexttrace-tinylinuxamd64,ntrlinuxamd64nexttracedarwinuniversal,nexttrace-tinydarwinuniversal,ntrdarwinuniversalnexttracewindowsamd64.exe,ntrwindowsamd64.exe
Get Started
NextTrace uses the ICMP protocol to perform TraceRoute requests by default, which supports both IPv4 and IPv6
# IPv4 ICMP Trace
nexttrace 1.0.0.1
URL
nexttrace http://example.com:8080/index.html?q=1
Table output (report mode): runs trace once and prints a final summary table
nexttrace --table 1.0.0.1
Machine-readable output: stdout is a single JSON document
nexttrace --raw 1.0.0.1
nexttrace --json 1.0.0.1
Realtime trace output to a custom file
nexttrace --output ./trace.log 1.0.0.1
Realtime trace output to the default log file
nexttrace --output-default 1.0.0.1
IPv4/IPv6 Resolve Only, and automatically select the first IP when there are multiple IPs
nexttrace --ipv4 g.co
nexttrace --ipv6 g.co
IPv6 ICMP Trace
nexttrace 2606:4700:4700::1111
Developer mode: set the ENV variable NEXTTRACE_DEVMODE=1 to make fatal errors panic with a stack trace
export NEXTTRACE_DEVMODE=1
Set TTL-group interval in normal traceroute mode (default: 300ms)
nexttrace -i 300 1.1.1.1
Disable Path Visualization With the -M parameter
nexttrace koreacentral.blob.core.windows.net
MapTrace URL: https://api.nxtrace.org/tracemap/html/c14e439e-3250-5310-8965-42a1e3545266.html
Disable MPLS display using the --disable-mpls / -e parameter or the NEXTTRACE_DISABLEMPLS environment variable
nexttrace --disable-mpls example.com
export NEXTTRACE_DISABLEMPLS=1PS: The route visualization module is an independent component, You can find its source code at nxtrace/traceMap. The routing visualization function requires the geographical coordinates of each Hop, but third-party APIs generally do not provide this information, so this function is currently only supported when used with LeoMoeAPI.
Mandatory Configuration Steps for Windows Users
- For Normal User Mode:
ICMP/ICMPv6 traffic.
netsh advfirewall firewall add rule name="All ICMP v4" dir=in action=allow protocol=icmpv4:any,any
netsh advfirewall firewall add rule name="All ICMP v6" dir=in action=allow protocol=icmpv6:any,any- For Administrator Mode:
WinDivert.
ICMP mode supports 1=Socket and 2=WinDivert (0=Auto). If running in Socket mode, the firewall must allow ICMP/ICMPv6.
On Windows, ICMPv6 without --tos (or with --tos 0) keeps using the native Socket send path. A non-zero ICMPv6 --tos requires WinDivert send support in addition to administrator privilege.
WinDivert can be automatically configured using the --init parameter, which extracts the runtime to the executable directory.
NextTrace now supports quick testing, and friends who have a one-time backhaul routing test requirement can use it
# IPv4 ICMP Fast Test (Beijing + Shanghai + Guangzhou + Hangzhou) in China Telecom / Unicom / Mobile / Education Network
nexttrace --fast-trace
You can also use TCP SYN for testing
nexttrace --fast-trace --tcp
You can also quickly test through a customized IP/DOMAIN list file
nexttrace --file /path/to/your/iplist.txt
CUSTOMIZED IP DOMAIN LIST FILE FORMAT
One IP/DOMAIN per line + space + description information (optional)
forExample:
106.37.67.1 BEIJING-TELECOM
240e:928:101:31a::1 BEIJING-TELECOM
bj.10086.cn BEIJING-MOBILE
2409:8080:0:1::1
223.5.5.5
NextTrace already supports route tracing for specified Network Devices
On macOS and Linux, --dev binds the requested source interface. On Windows, --dev resolves the source IP from the selected device and uses that source address for ICMP/TCP/UDP probes; it does not bind WinDivert or sockets to a real egress interface, so Windows routing may still choose a different path. The standalone --mtu mode follows the same source-address behavior and also uses the device name for local MTU lookup.
# Use eth0 network interface
nexttrace --dev eth0 2606:4700:4700::1111
Use eth0 network interface's IP
When using the network interface's IP for route tracing, note that the IP type to be traced should be the same as network interface's IP type (e.g. both IPv4)
nexttrace --source 204.98.134.56 9.9.9.9NextTrace can also use TCP and UDP protocols to perform Traceroute requests
# TCP SYN Trace
nexttrace --tcp www.bing.com
You can specify the port by yourself [here is 443], the default port is 80
nexttrace --tcp --port 443 2001:4860:4860::8888
UDP Trace
nexttrace --udp 1.0.0.1
You can specify the target port yourself [here it is 5353], the default is port 33494
nexttrace --udp --port 5353 1.0.0.1
For TCP/UDP Trace, you can specify the source port; by default, a fixed random port is used
(If you need to use a different random source port for each packet, please set the ENV variable NEXTTRACE_RANDOMPORT, or set the source port to -1)
nexttrace --tcp --source-port 14514 www.bing.comNextTrace also supports standalone path-MTU discovery mode
# Tracepath-style UDP PMTU discovery with live hop output
nexttrace --mtu 1.1.1.1
Reuse the normal GeoIP / RDNS knobs in mtu mode
nexttrace --mtu --data-provider IPInfo --language en 1.1.1.1
JSON output keeps the standalone mtu schema and now includes hop.geo
nexttrace --mtu --json 1.1.1.1--mtuis an independent UDP-only mode. It does not reuse the normal traceroute engine.- TTY output updates the current hop in place and adds color for hop state / PMTU highlights; redirected / piped output falls back to finalized line-by-line streaming without ANSI.
--mtu --jsonprints only the standalone MTU JSON document on stdout.- GeoIP, RDNS,
--data-provider,--language,--no-rdns,--always-rdns, and--dot-serverall apply to this mode.
NextTrace also supports standalone CDN speed testing mode
# Apple CDN backend (default)
nexttrace --speed
Cloudflare backend
nexttrace --speed --speed-provider cloudflare
Dedicated speed help
nexttrace --speed --help
Machine-readable output
nexttrace --speed --json --non-interactive --no-metadata
Pin to a specific candidate IP, or bind a source address / device
nexttrace --speed --endpoint 1.2.3.4
nexttrace --speed --source 192.0.2.10
nexttrace --speed --dev eth0--speedis available only in the fullnexttraceflavor.nexttrace-tinyandntrdo not register it.- Main
nexttrace --helponly exposes the top-level--speedentry. Detailed speed flags live undernexttrace --speed --help. - Backends:
apple(default) andcloudflare. - Reused common flags:
--json,--language,--no-color,--dot-server,--timeout,--source,--dev. - Speed-specific flags:
--speed-provider,--max,--threads,--latency-count,--non-interactive,--endpoint,--no-metadata. - Default terminal output includes candidate endpoints, the selected endpoint, client/server metadata, idle latency, download/upload single-thread and multi-thread rounds, loaded latency, total traffic, warnings, and degraded status.
--jsonprints exactly one JSON document to stdout.- Exit codes:
0= success,2= degraded completion,1= failure,130= interrupted.
NextTrace can annotate IP literals in text streams
# Annotate a single line
nexttrace --nali 1.1.1.1
Annotate pipeline output
dig example.com +short | nexttrace --nali --data-provider IPInfo --language en--naliis available only in the fullnexttraceflavor.nexttrace-tinyandntrdo not register it.- It only annotates IPv4/IPv6 literals and reuses NextTrace GeoIP providers. CDN/CNAME matching, offline databases, update logic, and nali-specific paths are not bundled.
- Reused common flags:
--data-provider,--language,--dot-server,--timeout,--dn42,-4, and-6. - This text annotation mode is inspired by zu1k/nali, which is licensed under the MIT License.
NextTrace also supports some advanced functions, such as ttl control, concurrent probe packet count control, mode switching, etc.
# Display 2 latency samples per hop
nexttrace --queries 2 www.hkix.net
Allow up to 10 probe packets per hop to collect those samples
(NextTrace stops earlier if it has already got the replies requested by --queries)
nexttrace --max-attempts 10 www.hkix.net
or use the ENV variable NEXTTRACE_MAXATTEMPTS to persist across runs
export NEXTTRACE_MAXATTEMPTS=10
No concurrent probe packets, only one probe packet is sent at a time
nexttrace --parallel-requests 1 www.hkix.net
Start Trace with TTL of 5, end at TTL of 10
nexttrace --first 5 --max-hops 10 www.decix.net
In addition, an ENV is provided to set whether to mask the destination IP and omit its hostname
export NEXTTRACE_ENABLEHIDDENDSTIP=1
Turn off the IP reverse parsing function
nexttrace --no-rdns www.bbix.net
Set the probe packet size to 1024 bytes (inclusive IP + probe headers)
nexttrace --psize 1024 example.com
Randomize each probe packet size up to 1500 bytes
nexttrace --psize -1500 example.com
Set the TOS / traffic class field
nexttrace -Q 46 example.com
Feature: print Route-Path diagram
Route-Path diagram example:
AS6453 Tata Communication「Singapore『Singapore』」
╭╯
╰AS9299 Philippine Long Distance Telephone Co.「Philippines『Metro Manila』」
╭╯
╰AS36776 Five9 Inc.「Philippines『Metro Manila』」
╭╯
╰AS37963 Aliyun「ALIDNS.COM『ALIDNS.COM』」
nexttrace --route-path www.time.com.my
Disable color output
nexttrace --no-color 1.1.1.1
or use ENV
export NO_COLOR=1Advanced tuning quick guide
| Flag | What it controls | Default / starting point | When to change it | | --- | --- | --- | --- | | --queries | Samples per hop in normal traceroute; explicit probe count per hop in MTR | traceroute: 3; MTR report: 10 when omitted; MTR TUI/raw: unlimited when omitted | Raise to 5-10 on unstable paths | | --max-attempts | Hard cap on probe packets per hop | auto-sized from --queries | Raise on lossy links when replies arrive slowly | | --parallel-requests | Total in-flight probes across TTLs | 18 | Use 1 on multipath/load-balanced paths; keep 6-18 on stable links | | --send-time | Gap between packets inside one TTL group | 50ms | Raise to 100-200ms on rate-limited devices; ignored in MTR | | --ttl-time | Gap between TTL groups in traceroute; per-hop interval in MTR | traceroute: 300ms; MTR: 1000ms when omitted | Lower to speed up; raise on remote/rate-limited paths | | --timeout | Per-probe timeout | 1000ms | Raise to 2000-3000ms for intercontinental or high-loss paths | | --psize | Probe packet size | Protocol/IP-family minimum | Inclusive IP + probe headers; negative values randomize each probe up to abs(value); sizes above the egress/path MTU may fragment on wire | | -Q, --tos | IP TOS / traffic class | 0 | Set DSCP/TOS style marking in the IP header; on Windows only ICMPv6 with a non-zero value requires WinDivert |
These probe knobs are CLI-only today; nt_config.yaml does not yet store them. If you want reusable profiles, keep them in shell aliases or small wrapper scripts.
# Conservative profile for multipath or ECMP networks
nexttrace --parallel-requests 1 --send-time 100 --ttl-time 500 --timeout 2000 example.com
Faster profile for stable single-path networks
nexttrace --parallel-requests 18 --send-time 20 --ttl-time 150 example.com
Lossy long-haul profile
nexttrace --queries 5 --max-attempts 10 --timeout 2500 example.comNextTrace supports MTR (My Traceroute) continuous probing mode
# MTR mode: continuous probing with ICMP (default), refreshes table in real-time
nexttrace -t 1.1.1.1
or equivalently:
nexttrace --mtr 1.1.1.1
MTR mode with TCP SYN probing
nexttrace -t --tcp --port 443 www.bing.com
MTR mode with UDP probing
nexttrace -t --udp 1.0.0.1
Set per-hop probe interval (default: 1000ms in MTR; -z/--send-time is ignored in MTR mode)
nexttrace -t -i 500 1.1.1.1
Limit the max probes per hop (default: infinite in TUI, 10 in report mode)
nexttrace -t -q 20 1.1.1.1
Report mode: probe each hop N times then print a final summary (like mtr -r)
nexttrace -r 1.1.1.1 # = --mtr --report, 10 probes per hop by default
nexttrace -r -q 5 1.1.1.1 # 5 probes per hop
Wide report: no host column truncation (like mtr -rw)
nexttrace -w 1.1.1.1 # = --mtr --report --wide
Show PTR and IP together (PTR first, IP in parentheses) in MTR output
nexttrace --mtr --show-ips 1.1.1.1
nexttrace -r --show-ips 1.1.1.1
nexttrace -w --show-ips 1.1.1.1
MTR raw stream mode (machine-friendly, one event per line)
nexttrace --mtr --raw 1.1.1.1
nexttrace -r --raw 1.1.1.1
Combine with other options
nexttrace -t --tcp --max-hops 20 --first 3 --no-rdns 8.8.8.8When running in a terminal (TTY), MTR mode uses an interactive full-screen TUI:
q/Q— quit (restores terminal, no output left behind)p— pause probingSPACE— resume probingr— reset statistics (counters are cleared, display mode is preserved)y— cycle host display mode: ASN → City → Owner → Fulln— toggle host name display:
--show-ips: PTR (IP) ↔ IP only
e— toggle MPLS label display on/offd/D— toggle the optional history display; the default TUI remains the classic metric tableg/G— in history display only, cycle History chart mode: heatmap → bars → sparkline- The TUI header displays source → destination, with
--source/--devinformation when specified. - When using LeoMoeAPI, the preferred API IP address is shown in the header.
- Uses the alternate screen buffer, so your previous terminal history is preserved on exit.
- When stdin is not a TTY (e.g. piped), it falls back to a simple table refresh.
Host, Last, Avg, Loss, and History when toggled with d. The History column uses a fixed 100ms latency scale. Unicode blocks/sparklines are used by default; with --no-color, plain ASCII is used and timeouts are shown as x.
Acknowledgement: the optional MTR history display is inspired by TraceBar, a macOS continuous traceroute monitor licensed under the MIT License.
The report mode (-r/--report) produces a one-shot summary after all probes complete, suitable for scripting:
Start: 2025-07-14T09:12:00+08:00
HOST: myhost Loss% Snt Last Avg Best Wrst StDev
1. one.one.one.one 0.0% 10 1.23 1.45 0.98 2.10 0.32
2. 10.0.0.2 100.0% 10 0.00 0.00 0.00 0.00 0.00Rows shown as (waiting for reply) keep the same table layout; the metric cells on that row are left blank.
In non-wide report mode, NextTrace intentionally keeps the host column compact:
- only
PTR/IPis shown - no Geo API lookup is performed
- no ASN / owner / location fields are shown
- MPLS labels are hidden
-w / --wide) keeps the current full-information behavior, including Geo-derived fields and MPLS output.
When --raw is used together with MTR (--mtr, -r, or -w), NextTrace enters MTR raw stream mode.
If the active data provider is LeoMoeAPI, NextTrace first prints one uncolored API info preamble line:
[NextTrace API] preferred API IP - [2403:18c0:1001:462:dd:38ff:fe48:e0c5] - 21.33ms - DMIT.NRTAfter that, it prints one |-delimited event per line:
4|84.17.33.106|po66-3518.cr01.nrt04.jp.misaka.io|0.27|60068|Japan|Tokyo|Tokyo||cdn77.com|35.6804|139.7690Field order:
ttl|ip|ptr|rtt|asn|country|prov|city|district|owner|lat|lng
Timeout rows keep the same 12-column layout:
ttl|*||||||||||
In MTR mode (--mtr, -r, -w, including --raw), -i/--ttl-time sets the per-hop probe interval: how long to wait between successive probes to the same hop (default: 1000ms when omitted). -z/--send-time is ignored in MTR mode.
Note:>--show-ipsonly takes effect in MTR mode (--mtr,-r,-w); otherwise it is ignored.
Note:--mtrcannot be used together with--table,--classic,--json,--output,--output-default,--route-path,--from,--fast-trace,--file, or--deploy.
NextTrace supports users to select their own IP API (currently supports: LeoMoeAPI, IP.SB, IPInfo, IPInsight, IPAPI.com, IPInfoLocal, CHUNZHEN)
# You can specify the IP database by yourself [IP-API.com here], if not specified, LeoMoeAPI will be used
nexttrace --data-provider ip-api.com
Note There are frequency limits for free queries of the ipinfo and IPInsight APIs. You can purchase services from these providers to remove the limits
If necessary, you can clone this project, add the token provided by ipinfo or IPInsight and compile it yourself
Fill the token to: ipgeo/tokens.go
Note For the offline database IPInfoLocal, please download it manually and rename it to ipinfoLocal.mmdb. (You can download it from here: https://ipinfo.io/signup?ref=free-database-downloads)
Current directory, nexttrace binary directory and FHS directories (Unix-like) will be searched.
To customize it, please use environment variables,
export NEXTTRACE_IPINFOLOCALPATH=/xxx/yyy.mmdb
Please be aware: Due to the serious abuse of IP.SB, you will often be not able to query IP data from this source
IP-API.com has a stricter restiction on API calls, if you can't query IP data from this source, please try again in a few minutes
The Pure-FTPd IP database defaults to using http://127.0.0.1:2060 as the query interface. To customize it, please use environment variables
export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
You can use https://github.com/freshcn/qqwry to build your own Pure-FTPd IP database service
You can also specify the default IP database by setting an environment variable
export NEXTTRACE_DATAPROVIDER=ipinfoLeoMoeAPI keeps the old v3 WebSocket API as the default when no NextTrace API v4 token is available. To use the NextTrace API v4 HTTP GeoIP endpoint for the current shell session, run the setup command and paste your token:
# Token page:
GET https://api.nxtrace.org/v4/api-tokens
nexttrace -x
nexttrace -x stores the token in temporary files: one scoped to the parent process ID, which is normally your current shell, and one same-user fallback file for wrapper commands such as go run. Later nexttrace commands first read the real NEXTTRACEAPIV4TOKEN, then the parent-PID file, then the fallback file, and load the value into the process-local environment. The command does not write shell profiles, permanent environment variables, or ntconfig.yaml.
With NEXTTRACEAPIV4_TOKEN set and the active provider still LeoMoeAPI, NextTrace queries GET https://api.nxtrace.org/v4/ipGeo?ip=<ip> with X-NextTrace-Token: <token>. The request has no JSON body. Successful responses are direct GeoIP JSON mapped to the normal output fields; quota metadata is exposed only in headers (X-NextTrace-Quota-Remaining, X-NextTrace-Quota-Expires-At, X-NextTrace-Quota-Cost, X-NextTrace-Quota-Source) and does not change the default output format. Error responses prefer {"error":{"message":"..."}}; known statuses include 400 for empty/illegal IP, 401 unauthorized, 429 quota exhausted, and 500 internal server error. NextTrace API v4 token failures do not fall back to the old v3 WebSocket API.
NextTrace supports mixed parameters and shortened parameters
Example:
nexttrace --data-provider IPAPI.com --max-hops 20 --tcp --port 443 --queries 5 --no-rdns 1.1.1.1
nexttrace -tcp --queries 2 --parallel-requests 1 --table --route-path 2001:4860:4860::8888
Equivalent to: nexttrace -d ip-api.com -m 20 -T -p 443 -q 5 -n 1.1.1.1 nexttrace -T -q 2 --parallel-requests 1 --table -P 2001:4860:4860::8888
Globalping
Globalping provides access to thousands of community-hosted probes to run network tests and measurements.
Run traceroute from a specified location by using the --from flag. The location field accepts continents, countries, regions, cities, ASNs, ISPs, or cloud regions.
nexttrace google.com --from Germany
nexttrace google.com --from comcast+californiaA limit of 250 tests per hour is set for all anonymous users. To double the limit to 500 per hour please set the GLOBALPING_TOKEN environment variable with your token.
export GLOBALPINGTOKEN=yourtoken_hereIP Database
We use bgp.tools as a data provider for routing tables.
NextTrace BackEnd is now open-source.
https://github.com/sjlleo/nexttrace-backend
NextTrace LeoMoeAPI now utilizes the Proof of Work (POW) mechanism to prevent abuse, where NextTrace introduces the powclient library as a client-side component. Both the POW CLIENT and SERVER are open source, and everyone is welcome to use them. (Please direct any POW module-related questions to the corresponding repositories)
- GitHub - tsosunchia/powclient: Proof of Work CLIENT for NextTrace
- GitHub - tsosunchia/powserver: Proof of Work SERVER for NextTrace
API DEMO can refer to here
Environment Variables
NextTrace currently reads the following environment variables. For boolean switches, only 1 and 0 are recognized; other values fall back to the built-in default. For consistency, restart NextTrace after changing them.
Core Runtime / Network
| Variable | Default | Description | | --- | --- | --- | | NEXTTRACE_DEVMODE | 0 | Turn fatal errors into panics with stack traces for debugging. | | NEXTTRACE_DEBUG | unset | Print detected environment values while GetEnv* helpers parse them. | | NEXTTRACE_DISABLEMPLS | 0 | Disable MPLS display globally, similar to --disable-mpls. | | NEXTTRACE_ENABLEHIDDENDSTIP | 0 | Mask the destination IP and omit its hostname in output. | | NEXTTRACE_RANDOMPORT | 0 | Use a different random source port for each TCP/UDP probe. | | NEXTTRACE_MAXATTEMPTS | auto | Provide a default --max-attempts value when the CLI flag is not set. | | NEXTTRACE_ICMPMODE | 0 | Provide a default --icmp-mode value (0=auto, 1=socket, 2=WinDivert on Windows). | | NEXTTRACE_UNINTERRUPTED | 0 | When used together with --raw, rerun traceroute continuously instead of stopping after one round. | | NEXTTRACE_PROXY | unset | Outbound proxy URL for HTTP / WebSocket requests used by PoW, Geo APIs, tracemap, etc. | | NEXTTRACE_DATAPROVIDER | unset | Override the default IP geolocation provider (for example ipinfo). |
Service / Web / Backend
| Variable | Default | Description | | --- | --- | --- | | NEXTTRACE_HOSTPORT | api.nxtrace.org | Override the backend host or host:port used by LeoMoeAPI, tracemap, and FastIP flows. | | NEXTTRACE_TOKEN | unset | Pre-supplied LeoMoeAPI bearer token; when present, token fetching via PoW is skipped. | | NEXTTRACEAPIV4_TOKEN | unset | LeoMoeAPI NextTrace API v4 HTTP GeoIP token. When unset, NextTrace also checks the temporary token files written by nexttrace -x; if neither exists, LeoMoeAPI keeps using the old v3 WebSocket / PoW flow. | | NEXTTRACE_POWPROVIDER | api.nxtrace.org | Select the PoW provider. The built-in non-default alias is sakura. | | NEXTTRACEDEPLOYADDR | unset | Default listen address for --deploy when --listen is not provided. | | NEXTTRACEDEPLOYTOKEN | unset | Token for --deploy WebUI/API/WebSocket/MCP access. CLI --deploy-token takes precedence. | | NEXTTRACEALLOWCROSS_ORIGIN | 0 | Only for --deploy: allow cross-origin browser access to the Web UI / API. Disabled by default for safety. |
IP Database / Third-Party Providers
| Variable | Default | Description | | --- | --- | --- | | NEXTTRACE_IPINFOLOCALPATH | auto search | Full path to ipinfoLocal.mmdb for the IPInfoLocal provider. | | NEXTTRACE_CHUNZHENURL | http://127.0.0.1:2060 | Base URL of the Chunzhen lookup service. | | NEXTTRACEIPINFOTOKEN | unset | Token for the IPInfo provider. | | NEXTTRACEIPINSIGHTTOKEN | unset | Token for the IPInsight provider. | | NEXTTRACEIPAPIBASE | provider built-in URL | Override the base URL used by compatible IP API clients in the current implementation (IPInfo, IPInsight, ip-api.com). | | IPDBONEBASEURL | https://api.ipdb.one | Override the IPDB.One API base URL. | | IPDBONEAPIID | unset | IPDB.One API ID. | | IPDBONEAPIKEY | unset | IPDB.One API key. | | GLOBALPING_TOKEN | unset | Authentication token for Globalping; raises the anonymous hourly limit when provided. |
Config Discovery
| Variable | Default | Description | | --- | --- | --- | | XDGCONFIGHOME | OS / shell default | If set, NextTrace also searches $XDGCONFIGHOME/nexttrace for nt_config.yaml. |
For full usage list, please refer to the usage menu
Usage: nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp]
[-U|--udp] [--speed] [--nali] [-F|--fast-trace]
[-p|--port <integer>] [--icmp-mode <integer>] [-q|--queries <integer>]
[--max-attempts <integer>] [--parallel-requests <integer>]
[-m|--max-hops <integer>] [-d|--data-provider
(IP.SB|ip.sb|IPInfo|ipinfo|IPInsight|ipinsight|IPAPI.com|ip-api.com|IPInfoLocal|ipinfolocal|chunzhen|LeoMoeAPI|leomoeapi|ipdb.one|disable-geoip)]
[--pow-provider (api.nxtrace.org|sakura)] [-n|--no-rdns]
[-a|--always-rdns] [-P|--route-path] [--dn42] [-o|--output
"<value>"] [-O|--output-default] [--table] [--raw]
[-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map]
[-e|--disable-mpls] [-V|--version] [-x|--setup-api-v4-token]
[-s|--source "<value>"] [--source-port <integer>] [-D|--dev
"<value>"] [--listen "<value>"] [--deploy-token "<value>"]
[--mcp] [--deploy] [-z|--send-time <integer>]
[-i|--ttl-time <integer>] [--timeout <integer>]
[--psize <integer>] [--dot-server
(dnssb|aliyun|dnspod|google|cloudflare)] [-g|--language
(en|cn)] [-C|--no-color] [--from "<value>"] [-t|--mtr]
[-r|--report] [-w|--wide] [--show-ips] [-y|--ipinfo <integer>]
[--file "<value>"] [TARGET "<value>"]
Arguments:
-h --help Print help information --init Windows ONLY: Extract WinDivert runtime to executable directory --speed Run CDN speed test mode. See nexttrace --speed --help for details --nali Annotate IP literals in text using NextTrace GeoIP data -4 --ipv4 Use IPv4 only -6 --ipv6 Use IPv6 only -T --tcp Use TCP SYN for tracerouting (default dest-port is 80) -U --udp Use UDP SYN for tracerouting (default dest-port is 33494) -F --fast-trace One-Key Fast Trace to China ISPs -p --port Set the destination port to use. With default of 80 for "tcp", 33494 for "udp" --icmp-mode Windows ONLY: Choose the method to listen for ICMP packets (1=Socket, 2=WinDivert; 0=Auto) -q --queries Latency samples per hop. Increase to 5-10 on unstable paths for a steadier view. Default: 3 --max-attempts Advanced: hard cap on probe packets per hop. Leave unset for auto sizing; raise on lossy links if --queries is not enough --parallel-requests Advanced: total concurrent in-flight probes across TTLs. Use 1 on multipath/load-balanced paths; 6-18 is a good starting range on stable links. Default: 18 -m --max-hops Set the max number of hops (max TTL to be reached). Default: 30 -d --data-provider Choose IP Geograph Data Provider [IP.SB, IPInfo, IPInsight, IP-API.com, IPInfoLocal, CHUNZHEN, disable-geoip]. Default: LeoMoeAPI --pow-provider Choose PoW Provider [api.nxtrace.org, sakura] For China mainland users, please use sakura. Default: api.nxtrace.org -n --no-rdns Do not resolve IP addresses to their domain names -a --always-rdns Always resolve IP addresses to their domain names -P --route-path Print traceroute hop path by ASN and location --dn42 DN42 Mode -o --output Write trace result to FILE (RealtimePrinter only) -O --output-default Write trace result to the default log file (/tmp/trace.log) --table Output trace results as a final summary table (traceroute report mode) --raw Machine-friendly output. With MTR (--mtr/-r/-w), enables streaming raw event mode -j --json Output trace results as JSON -c --classic Classic Output trace results like BestTrace -f --first Start from the first_ttl hop (instead of 1). Default: 1 -M --map Disable Print Trace Map -e --disable-mpls Disable MPLS -V --version Print version info and exit -x --setup-api-v4-token Store a session-only NextTrace API v4 token in a temporary file and exit -s --source Use source address src_addr for outgoing packets --source-port Use source port src_port for outgoing packets -D --dev Use the specified network device for explicit source selection. On Windows, this selects the device source address; routing may still choose the egress interface --listen Set listen address for web console (e.g. 127.0.0.1:30080) --deploy-token Set bearer token for --deploy WebUI/API/WebSocket/MCP access --mcp Enable MCP endpoint under --deploy at /mcp --deploy Start the Gin powered web console -z --send-time Advanced: per-packet gap [ms] inside the same TTL group. Lower is faster; raise to 100-200ms on rate-limited links. Ignored in MTR mode. Default: 50 -i --ttl-time Advanced: TTL-group interval [ms] in normal traceroute. In MTR mode (--mtr/-r/-w, including --raw), this becomes per-hop probe interval. 500-1000ms is a good MTR starting range --timeout Per-probe timeout [ms]. Raise to 2000-3000 on slow intercontinental or high-loss paths. Default: 1000 --psize Probe packet size in bytes, inclusive IP and active probe headers. Default is the minimum legal size for the chosen protocol and IP family; raise for MTU or large-packet testing. Negative values randomize each probe up to abs(value). -Q --tos Set the IP type-of-service / traffic class value [0-255]. Default: 0 --dot-server Use DoT Server for DNS Parse [dnssb, aliyun, dnspod, google, cloudflare] -g --language Choose the language for displaying [en, cn]. Default: cn -C --no-color Disable Colorful Output --from Run traceroute via Globalping (https://globalping.io/network) from a specified location. The location field accepts continents, countries, regions, cities, ASNs, ISPs, or cloud regions. -t --mtr Enable MTR (My Traceroute) continuous probing mode -r --report MTR report mode (non-interactive, implies --mtr); can trigger MTR without --mtr -w --wide MTR wide report mode (implies --mtr --report); alone equals --mtr --report --wide --show-ips MTR only: display both PTR hostnames and numeric IPs (PTR first, IP in parentheses) -y --ipinfo Set initial MTR TUI host info mode (0-4). TUI only; ignored in --report/--raw. 0:IP/PTR 1:ASN 2:City 3:Owner 4:Full. Default: 0 --file Read IP Address or domain name from file TARGET Trace target: IPv4 address (e.g. 8.8.8.8), IPv6 address (e.g. 2001:db8::1), domain name (e.g. example.com), or URL (e.g. https://example.com)
Project screenshot
OpenTrace
OpenTrace is the cross-platform GUI version of NextTrace developed by @Archeb, bringing a familiar but more powerful user experience.
This software is still in the early stages of development and may have many flaws and errors. We value your feedback.
https://github.com/Archeb/opentrace
GlobalTrace
GlobalTrace is an open-source Globalping x NextTrace web traceroute project. It uses Globalping's worldwide probe network to run MTR measurements from multiple regions, then enriches hop IPs with the NextTrace / NTrace backbone IP database for GeoIP, ASN, and network ownership details.
Website: https://lg.nxtrace.org
Project: nxtrace/GlobalTrace
NextTrace Web
NextTrace Web is a web-based server implementation of NextTrace in the MTR style, offering various deployment options including Docker.
https://github.com/nxtrace/nexttraceweb
Deploy WebUI and MCP
The full nexttrace binary can expose the local WebUI/API/WebSocket server:
nexttrace --deployMCP is a deploy submode and is exposed over the same network stack at /mcp:
nexttrace --deploy --mcp
nexttrace --deploy --mcp --listen 0.0.0.0:1080 --deploy-token "$TOKEN"Loopback listen addresses (127.0.0.1, ::1, localhost) are tokenless by default. External listen addresses require a token; if none is set with --deploy-token or NEXTTRACEDEPLOYTOKEN, NextTrace generates one and prints it to stdout. API, WebSocket, and MCP clients may use Authorization: Bearer <token> or X-NextTrace-Token; browser WebUI users can sign in at /auth/login.
Register MCP in Agent clients
Start NextTrace first. The MCP endpoint is Streamable HTTP, not stdio:
http://127.0.0.1:1080/mcpFor external listeners or manually configured tokens, pass the token in an HTTP header. Do not put deploy tokens in URL query strings.
Generic MCP client config:
{
"mcp": {
"servers": {
"nexttrace": {
"url": "http://127.0.0.1:1080/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}OpenClaw can save the same server definition with openclaw mcp set:
openclaw mcp set nexttrace '{
"url": "http://127.0.0.1:1080/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer <token>"
}
}'openclaw mcp set only saves the MCP server definition. It does not start NextTrace or verify that the endpoint is reachable, so run nexttrace --deploy --mcp first.
Useful first tool calls for Agents:
nexttrace_capabilitiesnexttrace_traceroutenexttraceglobalpingtracenexttraceglobalpinglimits
NextTraceroute
NextTraceroute is a root-free Android route tracing application that defaults to using the NextTrace API, developed by @surfaceocean. Thank you to all the test users for your enthusiastic support. This app has successfully passed the closed testing phase and is now officially available on the Google Play Store.
https://github.com/nxtrace/NextTraceroute 
LeoMoeAPI Credits
NextTrace focuses on Golang Traceroute implementations, and its LeoMoeAPI geolocation information is not supported by raw data, so a commercial version is not possible.
The LeoMoeAPI data is subject to copyright restrictions from multiple data sources, and is only used for the purpose of displaying the geolocation of route tracing.
- We would like to credit samleong123 for providing nodes in Malaysia, TOHUNET Looking Glass for global nodes, and Ping.sx from Misaka, where more than 80% of reliable calibration data comes from ping/mtr reports.
- At the same time, we would like to credit isyekong for their contribution to rDNS-based calibration ideas and data. LeoMoeAPI is accelerating the development of rDNS resolution function, and has already achieved automated geolocation resolution for some backbone networks, but there are some misjudgments. We hope that NextTrace will become a One-Man ISP-friendly traceroute tool in the future, and we are working on improving the calibration of these ASN micro-backbones as much as possible.
- In terms of development, I would like to credit missuo and zhshch for their help with Go cross-compilation, design concepts and TCP/UDP Traceroute refactoring, and tsosunchia for their support on TraceMap.
- I would also like to credit FFEE_CO, TheresaQWQ, stydxm and others for their help. LeoMoeAPI has received a lot of support since its first release, so I would like to credit them all!
Cloudflare Support
This project is sponsored by Project Alexandria.
AIWEN TECH Support
This project is sponsored by AIWEN TECH. We’re pleased to enhance the accuracy and completeness of this project’s GEOIP lookups using AIWEN TECH City-Level IP Database, and to make it freely available to the public.
JetBrain Support
This Project uses JetBrain Open-Source Project License. We Proudly Develop By Goland.
Credits
Gubo Reliable Host Recommendation Website
IPInfo Provided most of the data support for this project free of charge
BGP.TOOLS Provided some data support for this project free of charge
PeeringDB Provided some data support for this project free of charge
Globalping An open-source and free project that provides global access to run network tests like traceroute
sjlleo The perpetual leader, founder, and core contributors
tsosunchia The project chair, infra maintainer, and core contributors
Yunlq An active community contributor
Others
- Although other third-party APIs are integrated in this project, please refer to the official website of the third-party APIs for specific TOS and AUP. If you encounter IP data errors, please contact them directly to correct them.
- For feedback related to corrections about IP information, we currently have two channels available:
correct#nxtrace.org (Please note that this email is only for correcting IP-related information. For other feedback, please submit an ISSUE)
- How to obtain the freshly baked binary executable of the latest commit?
- Common questions
