# bittorrent-tracker

> Simple, robust, BitTorrent tracker (client & server) implementation

Latest version **11.2.3** (published 2026-05-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install bittorrent-tracker
pnpm add bittorrent-tracker
yarn add bittorrent-tracker
bun add bittorrent-tracker
```

Provides the command `bittorrent-tracker`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 11.2.3 |
| Published | 2026-05-25 |
| First published | 2014-03-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 21 |
| Unpacked size | 115.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1942 |
| Author | WebTorrent LLC |
| Maintainers | feross, mafintosh, flet, watson, diegorbaquero, hicom150, jhiesey, webtorrent-bot, alxhotel |
| Keywords | bittorrent, p2p, peer, peer-to-peer, stream, torrent, tracker, wire |

## Links

- npm: https://www.npmjs.com/package/bittorrent-tracker
- Repository: https://github.com/webtorrent/bittorrent-tracker
- Homepage: https://github.com/webtorrent/bittorrent-tracker#readme
- Issues: https://github.com/webtorrent/bittorrent-tracker/issues
- Funding: https://github.com/sponsors/feross
- npm.io page: https://npm.io/package/bittorrent-tracker

## Dependencies (21)

- [ip](https://npm.io/package/ip.md) ^2.0.1
- [ws](https://npm.io/package/ws.md) ^8.17.0
- [lru](https://npm.io/package/lru.md) ^3.1.0
- [once](https://npm.io/package/once.md) ^1.4.0
- [debug](https://npm.io/package/debug.md) ^4.3.4
- [socks](https://npm.io/package/socks.md) ^2.8.3
- [bencode](https://npm.io/package/bencode.md) ^4.0.0
- [minimist](https://npm.io/package/minimist.md) ^1.2.8
- [run-series](https://npm.io/package/run-series.md) ^1.1.9
- [uint8-util](https://npm.io/package/uint8-util.md) ^2.2.5
- [chrome-dgram](https://npm.io/package/chrome-dgram.md) ^3.0.6
- [run-parallel](https://npm.io/package/run-parallel.md) ^1.2.0
- [compact2string](https://npm.io/package/compact2string.md) ^1.4.1
- [random-iterate](https://npm.io/package/random-iterate.md) ^1.0.1
- [string2compact](https://npm.io/package/string2compact.md) ^2.0.1
- [queue-microtask](https://npm.io/package/queue-microtask.md) ^1.2.3
- [bittorrent-peerid](https://npm.io/package/bittorrent-peerid.md) ^2.0.0
- [cross-fetch-ponyfill](https://npm.io/package/cross-fetch-ponyfill.md) ^1.0.3
- [unordered-array-remove](https://npm.io/package/unordered-array-remove.md) ^1.0.2
- [@thaunknown/simple-peer](https://npm.io/package/@thaunknown/simple-peer.md) ^10.0.8
- [@thaunknown/simple-websocket](https://npm.io/package/@thaunknown/simple-websocket.md) ^9.1.3

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 11.2.3 (latest) — 2026-05-25
- 11.2.2 — 2025-09-06
- 11.2.1 — 2025-01-19
- 11.2.0 — 2024-12-28
- 11.1.2 — 2024-08-13
- 11.1.1 — 2024-07-01
- 11.1.0 — 2024-05-22
- 11.0.2 — 2024-03-12
- 11.0.1 — 2024-01-16
- 11.0.0 — 2023-10-31
- 10.0.12 — 2023-08-09
- 10.0.11 — 2023-08-01
- 10.0.10 — 2023-06-16
- 10.0.9 — 2023-06-16
- 10.0.8 — 2023-06-07
- … 246 more at https://npm.io/package/bittorrent-tracker/versions

## README

# bittorrent-tracker [![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[ci-image]: https://img.shields.io/github/actions/workflow/status/webtorrent/bittorrent-tracker/ci.yml
[ci-url]: https://github.com/webtorrent/bittorrent-tracker/actions
[npm-image]: https://img.shields.io/npm/v/bittorrent-tracker.svg
[npm-url]: https://npmjs.org/package/bittorrent-tracker
[downloads-image]: https://img.shields.io/npm/dm/bittorrent-tracker.svg
[downloads-url]: https://npmjs.org/package/bittorrent-tracker
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

#### Simple, robust, BitTorrent tracker (client & server) implementation

![tracker visualization](img/img.png)

Node.js implementation of a [BitTorrent tracker](https://wiki.theory.org/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol), client and server.

A **BitTorrent tracker** is a web service which responds to requests from BitTorrent
clients. The requests include metrics from clients that help the tracker keep overall
statistics about the torrent. The response includes a peer list that helps the client
participate in the torrent swarm.

This module is used by [WebTorrent](http://webtorrent.io).

## features

- Includes client & server implementations
- Supports all mainstream tracker types:
  - HTTP trackers
  - UDP trackers ([BEP 15](http://www.bittorrent.org/beps/bep_0015.html))
  - WebTorrent trackers ([BEP forthcoming](http://webtorrent.io))
- Supports ipv4 & ipv6
- Supports tracker "scrape" extension
- Robust and well-tested
  - Comprehensive test suite (runs entirely offline, so it's reliable)
  - Used by popular clients: [WebTorrent](http://webtorrent.io), [peerflix](https://www.npmjs.com/package/peerflix), and [playback](https://mafintosh.github.io/playback/)
- Tracker statistics available via web interface at `/stats` or JSON data at `/stats.json`

Also see [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht).

### Tracker stats

![Screenshot](img/trackerStats.png)

## install

```
npm install bittorrent-tracker
```

## usage

### client

To connect to a tracker, just do this:

```js
import Client from 'bittorrent-tracker'

const requiredOpts = {
  infoHash: new Buffer('012345678901234567890'), // hex string or Buffer
  peerId: new Buffer('01234567890123456789'), // hex string or Buffer
  announce: [], // list of tracker server urls
  port: 6881 // torrent client port, (in browser, optional)
}

const optionalOpts = {
  // RTCPeerConnection config object (only used in browser)
  rtcConfig: {},
  // User-Agent header for http requests
  userAgent: '',
  // Custom webrtc impl, useful in node to specify [wrtc](https://npmjs.com/package/wrtc)
  wrtc: {},
  getAnnounceOpts: function () {
    // Provide a callback that will be called whenever announce() is called
    // internally (on timer), or by the user
    return {
      uploaded: 0,
      downloaded: 0,
      left: 0,
      customParam: 'blah' // custom parameters supported
    }
  },
  // Proxy options (used to proxy requests in node)
  proxyOpts: {
      // For WSS trackers this is always a http.Agent
      // For UDP trackers this is an object of options for the Socks Connection
      // For HTTP trackers this is either an undici Agent if using Node16 or later, or http.Agent if using versions prior to Node 16, ex:
      // import Socks from 'socks'
      // proxyOpts.socksProxy = new Socks.Agent(optionsObject, isHttps)
      // or if using Node 16 or later
      // import { socksDispatcher } from 'fetch-socks'
      // proxyOpts.socksProxy = socksDispatcher(optionsObject)
      socksProxy: new SocksProxy(socksOptionsObject),
      // Populated with socksProxy if it's provided
      httpAgent: new http.Agent(agentOptionsObject),
      httpsAgent: new https.Agent(agentOptionsObject)
  },
}

const client = new Client(requiredOpts)

client.on('error', function (err) {
  // fatal client error!
  console.log(err.message)
})

client.on('warning', function (err) {
  // a tracker was unavailable or sent bad data to the client. you can probably ignore it
  console.log(err.message)
})

// start getting peers from the tracker
client.start()

client.on('update', function (data) {
  console.log('got an announce response from tracker: ' + data.announce)
  console.log('number of seeders in the swarm: ' + data.complete)
  console.log('number of leechers in the swarm: ' + data.incomplete)
})

client.once('peer', function (addr) {
  console.log('found a peer: ' + addr) // 85.10.239.191:48623
})

// announce that download has completed (and you are now a seeder)
client.complete()

// force a tracker announce. will trigger more 'update' events and maybe more 'peer' events
client.update()

// provide parameters to the tracker
client.update({
  uploaded: 0,
  downloaded: 0,
  left: 0,
  customParam: 'blah' // custom parameters supported
})

// stop getting peers from the tracker, gracefully leave the swarm
client.stop()

// ungracefully leave the swarm (without sending final 'stop' message)
client.destroy()

// scrape
client.scrape()

client.on('scrape', function (data) {
  console.log('got a scrape response from tracker: ' + data.announce)
  console.log('number of seeders in the swarm: ' + data.complete)
  console.log('number of leechers in the swarm: ' + data.incomplete)
  console.log('number of total downloads of this torrent: ' + data.downloaded)
})
```

### server

To start a BitTorrent tracker server to track swarms of peers:

```js
import { Server } from 'bittorrent-tracker'
// Or import Server from 'bittorrent-tracker/server'

const server = new Server({
  udp: true, // enable udp server? [default=true]
  http: true, // enable http server? [default=true]
  ws: true, // enable websocket server? [default=true]
  stats: true, // enable web-based statistics? [default=true]
  trustProxy: false, // enable trusting x-forwarded-for header for remote IP [default=false]
  filter: function (infoHash, params, cb) {
    // Blacklist/whitelist function for allowing/disallowing torrents. If this option is
    // omitted, all torrents are allowed. It is possible to interface with a database or
    // external system before deciding to allow/deny, because this function is async.

    // It is possible to block by peer id (whitelisting torrent clients) or by secret
    // key (private trackers). Full access to the original HTTP/UDP request parameters
    // are available in `params`.

    // This example only allows one torrent.

    const allowed = (infoHash === 'aaa67059ed6bd08362da625b3ae77f6f4a075aaa')
    if (allowed) {
      // If the callback is passed `null`, the torrent will be allowed.
      cb(null)
    } else {
      // If the callback is passed an `Error` object, the torrent will be disallowed
      // and the error's `message` property will be given as the reason.
      cb(new Error('disallowed torrent'))
    }
  }
})

// Internal http, udp, and websocket servers exposed as public properties.
server.http
server.udp
server.ws

server.on('error', function (err) {
  // fatal server error!
  console.log(err.message)
})

server.on('warning', function (err) {
  // client sent bad data. probably not a problem, just a buggy client.
  console.log(err.message)
})

server.on('listening', function () {
  // fired when all requested servers are listening

  // HTTP
  const httpAddr = server.http.address()
  const httpHost = httpAddr.address !== '::' ? httpAddr.address : 'localhost'
  const httpPort = httpAddr.port
  console.log(`HTTP tracker: http://${httpHost}:${httpPort}/announce`)

  // UDP
  const udpAddr = server.udp.address()
  const udpHost = udpAddr.address
  const udpPort = udpAddr.port
  console.log(`UDP tracker: udp://${udpHost}:${udpPort}`)

  // WS
  const wsAddr = server.ws.address()
  const wsHost = wsAddr.address !== '::' ? wsAddr.address : 'localhost'
  const wsPort = wsAddr.port
  console.log(`WebSocket tracker: ws://${wsHost}:${wsPort}`)

})


// start tracker server listening! Use 0 to listen on a random free port.
const port = 0
const hostname = "localhost"
server.listen(port, hostname, () => {
  // Do something on listening...
})

// listen for individual tracker messages from peers:

server.on('start', function (addr) {
  console.log('got start message from ' + addr)
})

server.on('complete', function (addr) {})
server.on('update', function (addr) {})
server.on('stop', function (addr) {})

// get info hashes for all torrents in the tracker server
Object.keys(server.torrents)

// get the number of seeders for a particular torrent
server.torrents[infoHash].complete

// get the number of leechers for a particular torrent
server.torrents[infoHash].incomplete

// get the peers who are in a particular torrent swarm
server.torrents[infoHash].peers
```

The http server will handle requests for the following paths: `/announce`, `/scrape`. Requests for other paths will not be handled.

## multi scrape

Scraping multiple torrent info is possible with a static `Client.scrape` method:

```js
import Client from 'bittorrent-tracker'
// Or import Client from 'bittorrent-tracker/client'

Client.scrape({ announce: announceUrl, infoHash: [ infoHash1, infoHash2 ]}, function (err, results) {
  results[infoHash1].announce
  results[infoHash1].infoHash
  results[infoHash1].complete
  results[infoHash1].incomplete
  results[infoHash1].downloaded

  // ...
})
````

## command line

Install `bittorrent-tracker` globally:

```sh
$ npm install -g bittorrent-tracker
```

Easily start a tracker server:

```sh
$ bittorrent-tracker
http server listening on 8000
udp server listening on 8000
ws server listening on 8000
```

Lots of options:

```sh
$ bittorrent-tracker --help
  bittorrent-tracker - Start a bittorrent tracker server

  Usage:
    bittorrent-tracker [OPTIONS]

  If no --http, --udp, or --ws option is supplied, all tracker types will be started.

  Options:
    -p, --port [number]  change the port [default: 8000]
        --trust-proxy    trust 'x-forwarded-for' header from reverse proxy
        --interval       client announce interval (ms) [default: 600000]
        --http           enable http server
        --udp            enable udp server
        --ws             enable websocket server
    -q, --quiet          only show error output
    -s, --silent         show no output
    -v, --version        print the current version
```

## license

MIT. Copyright (c) [Feross Aboukhadijeh](https://feross.org) and [WebTorrent, LLC](https://webtorrent.io).

---
_Source: https://npm.io/package/bittorrent-tracker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._