9.19.0 • Public • Published

    bittorrent-tracker ci npm downloads javascript style guide

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

    tracker visualization

    Node.js implementation of a BitTorrent tracker, 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.


    • Includes client & server implementations
    • Supports all mainstream tracker types:
    • Supports ipv4 & ipv6
    • Supports tracker "scrape" extension
    • Robust and well-tested
    • Tracker statistics available via web interface at /stats or JSON data at /stats.json

    Also see bittorrent-dht.

    Tracker stats



    npm install bittorrent-tracker



    To connect to a tracker, just do this:

    var Client = require('bittorrent-tracker')
    var 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)
    var 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](
      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 config object
      proxyOpts: {
          // Socks proxy options (used to proxy requests in node)
          socksProxy: {
              // Configuration from socks module (
              proxy: {
                  // IP Address of Proxy (Required)
                  ipaddress: "",
                  // TCP Port of Proxy (Required)
                  port: 1080,
                  // Proxy Type [4, 5] (Required)
                  // Note: 4 works for both 4 and 4a.
                  // Type 4 does not support UDP association relay 
                  type: 5,
                  // SOCKS 4 Specific:
                  // UserId used when making a SOCKS 4/4a request. (Optional)
                  userid: "someuserid",
                  // SOCKS 5 Specific:
                  // Authentication used for SOCKS 5 (when it's required) (Optional)
                  authentication: {
                      username: "Josh",
                      password: "somepassword"
              // Amount of time to wait for a connection to be established. (Optional)
              // - defaults to 10000ms (10 seconds)
              timeout: 10000
          // NodeJS HTTP agents (used to proxy HTTP and Websocket requests in node)
          // Populated with Socks.Agent if socksProxy is provided
          httpAgent: {},
          httpsAgent: {}
    var client = new Client(requiredOpts)
    client.on('error', function (err) {
      // fatal client error!
    client.on('warning', function (err) {
      // a tracker was unavailable or sent bad data to the client. you can probably ignore it
    // start getting peers from the tracker
    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) //
    // announce that download has completed (and you are now a seeder)
    // force a tracker announce. will trigger more 'update' events and maybe more 'peer' events
    // provide parameters to the tracker
      uploaded: 0,
      downloaded: 0,
      left: 0,
      customParam: 'blah' // custom parameters supported
    // stop getting peers from the tracker, gracefully leave the swarm
    // ungracefully leave the swarm (without sending final 'stop' message)
    // 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)


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

    const Server = require('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.
        } 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.on('error', function (err) {
      // fatal server error!
    server.on('warning', function (err) {
      // client sent bad data. probably not a problem, just a buggy client.
    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 =
      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
    // get the number of seeders for a particular torrent
    // get the number of leechers for a particular torrent
    // get the peers who are in a particular torrent swarm

    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:

    var Client = require('bittorrent-tracker')
    Client.scrape({ announce: announceUrl, infoHash: [ infoHash1, infoHash2 ]}, function (err, results) {
      // ...

    command line

    Install bittorrent-tracker globally:

    $ npm install -g bittorrent-tracker

    Easily start a tracker server:

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

    Lots of options:

    $ bittorrent-tracker --help
      bittorrent-tracker - Start a bittorrent tracker server
        bittorrent-tracker [OPTIONS]
      If no --http, --udp, or --ws option is supplied, all tracker types will be started.
        -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


    MIT. Copyright (c) Feross Aboukhadijeh and WebTorrent, LLC.


    npm i bittorrent-tracker

    DownloadsWeekly Downloads






    Unpacked Size

    109 kB

    Total Files


    Last publish


    • alxhotel
    • feross
    • mafintosh
    • flet
    • watson
    • diegorbaquero
    • hicom150
    • jhiesey
    • webtorrent-bot