bittorrent-tracker: a BitTorrent tracker library
/bittorrent-tracker
bittorrent-tracker is a Node.js library implementing the BitTorrent tracker protocol for both client and server, covering HTTP, UDP, and WebSocket transports in one codebase. Reach for it when you need a tracker server or a client that talks to one, in Node or in the browser, without writing the wire protocol by hand. Skip it if you need DHT-based peer discovery instead of a central tracker; that's a separate package.
Understanding bittorrent-tracker
bittorrent-tracker is an npm package containing a Node.js implementation of a BitTorrent tracker, the service that BitTorrent clients report progress to and get a peer list from. It bundles a client and a server, and the server speaks HTTP, UDP, and WebSocket at once, covering both classic BitTorrent clients and browser-based WebTorrent peers.
Core capabilities and supported protocols
- โBundles both client and server implementations in one package, per the README.
- โSupports HTTP trackers, UDP trackers (BEP 15), and WebTorrent's WebSocket tracker protocol, covering both classic BitTorrent clients and browser peers.
- โHandles both IPv4 and IPv6 addressing, per the README.
- โImplements the tracker scrape extension for querying swarm stats without a full announce.
- โShips a test suite that the README says runs completely offline.
- โExposes tracker statistics through a web interface at /stats and as JSON at /stats.json.
- โThe client's optional proxyOpts route WSS, UDP (via SOCKS), and HTTP tracker requests through a proxy.
Installation and setup
Install with `npm install bittorrent-tracker` to use it as a client/server library inside a Node or browser project. To run the standalone CLI tracker server, install it globally instead: `npm install -g bittorrent-tracker`, which adds a `bittorrent-tracker` command. Running that command with no flags starts HTTP, UDP, and WebSocket servers together on port 8000 by default; pass `--help` to see the full flag list, including `-p`/`--port` to change the port and `--trust-proxy` to trust the `x-forwarded-for` header behind a reverse proxy.
Strengths
- โOne package covers both tracker client and server code, so you don't need separate libraries to test your own tracker against your own client.
- โThree transports in one server: HTTP, UDP, and WebSocket can all run from the same Server instance, per the README's udp/http/ws options.
- โThe scrape extension plus the /stats and /stats.json endpoints give visibility into swarm size without writing custom accounting.
- โThe filter option is a real hook for building a private or whitelisted tracker, with access to the full request params inside the callback.
- โThe README says the client is used by other real projects: WebTorrent, peerflix, and playback.
Scope and considerations
- โณThe README doesn't give a BEP number for the WebTorrent WebSocket tracker protocol; it's marked as 'BEP forthcoming,' so that half isn't formally standardized yet.
- โณThe server's filter callback is the only access-control mechanism described; there's no built-in authentication, rate limiting, or persistence layer in the README.
- โณNo documented benchmarks exist for peer or torrent scale.
- โณThe HTTP server only answers `/announce` and `/scrape`; anything else goes unhandled, per the README.
- โณProxy behavior differs by Node version (undici Agent on Node 16+, http.Agent before that) but only appears as a code comment in the client options, not a full explanation.
Other BitTorrent tracker solutions
Common questions
bittorrent-tracker supports HTTP trackers, UDP trackers (BEP 15), and WebTorrent's WebSocket-based tracker protocol, plus the tracker scrape extension for swarm statistics, all from the same server instance.
The client half of bittorrent-tracker runs in the browser as well as Node.js, and its optional `rtcConfig` and `wrtc` settings support the WebRTC connections that browser-based WebTorrent peers use to reach each other.
bittorrent-tracker's server exposes a web-based statistics page at `/stats` and the same data as JSON at `/stats.json` when the `stats` option is enabled, and the client can call `scrape()` for per-torrent seeder, leecher, and download counts.
bittorrent-tracker is released under the MIT license, copyright Feross Aboukhadijeh and WebTorrent, LLC.
bittorrent-tracker's Server constructor accepts a `filter` callback that gets the info hash, request params, and an async callback, letting you allow or reject torrents by info hash, peer ID, or a secret key before the tracker responds.
bittorrent-tracker's README lists IPv6 support alongside IPv4 for both the client and server sides of the tracker protocol.
The problem it solves
Browser-based BitTorrent clients like WebTorrent can't open a raw UDP socket or an arbitrary TCP connection the way a native BitTorrent client can, so they can't talk to a plain HTTP or UDP tracker directly. bittorrent-tracker's server answers over WebSocket as well as HTTP and UDP from the same process, and its client speaks whichever protocol the tracker in `announce` uses, so one Node codebase can serve or contact trackers for both browser and native peers instead of needing separate tracker software per protocol.
Best use cases
- โขRunning your own BitTorrent tracker server for an app you control, using the CLI or the Server class instead of depending on a public tracker.
- โขBuilding a WebTorrent-style browser app that needs a client library to announce to trackers over WebSocket and pull peer lists.
- โขBuilding a private tracker that whitelists specific torrents, using the server's filter callback to allow or block by info hash, peer ID, or a secret key.
- โขPulling live swarm stats (seeders, leechers, downloads) for one or more torrents via the client's scrape() method or the server's /stats.json endpoint.
How to use
As a client, import `Client` from `bittorrent-tracker`, construct it with an `infoHash`, a `peerId`, a list of `announce` URLs, and a `port`, then call `client.start()` to begin announcing; listen for `'peer'` events to get addresses of other swarm members and `'update'` events for seeder/leecher counts, and call `client.stop()` or `client.destroy()` to leave the swarm gracefully or immediately. As a server, import `Server` and construct it with `udp`, `http`, `ws`, and `stats` booleans to choose which transports run, then call `server.listen(port, hostname)`; the running instance exposes `server.torrents`, keyed by info hash, with `complete`, `incomplete`, and `peers` fields per torrent, and only responds to `/announce` and `/scrape` requests. From the command line, running the globally installed `bittorrent-tracker` binary with no flags starts all three transports on port 8000, and `--http`, `--udp`, or `--ws` flags let you run just one.
Who should try it โ and who should skip
Try bittorrent-tracker if you're building anything that needs to run or talk to a BitTorrent tracker from Node or the browser: a WebTorrent-style app, a private tracker with torrent whitelisting, or test infrastructure for other BitTorrent tooling. Skip it if you want tracker-free swarm discovery via DHT, since that's a separate package (bittorrent-dht) and a different protocol, or if you need a tracker built outside the Node.js ecosystem for a non-JS deployment.
Related repositories
Want a second opinion on bittorrent-tracker?
Ask an AI that can read this page โ one click and you get its take on bittorrent-tracker.