# torrent-discovery

> Discover BitTorrent and WebTorrent peers

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

## Install

```sh
npm install torrent-discovery
pnpm add torrent-discovery
yarn add torrent-discovery
bun add torrent-discovery
```

## 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.0.21 |
| Published | 2026-05-25 |
| First published | 2014-08-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=16.0.0 |
| Dependencies | 5 |
| Unpacked size | 31.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 228 |
| Author | WebTorrent LLC |
| Maintainers | feross, mafintosh, flet, watson, diegorbaquero, hicom150, jhiesey, webtorrent-bot, alxhotel |
| Keywords | webtorrent, torrent, bittorrent, peers, discovery, tracker, dht, lsd, trackers, find peers, peer-to-peer, peer discovery |

## Links

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

## Dependencies (5)

- [debug](https://npm.io/package/debug.md) ^4.4.3
- [run-parallel](https://npm.io/package/run-parallel.md) ^1.2.0
- [bittorrent-dht](https://npm.io/package/bittorrent-dht.md) ^11.0.12
- [bittorrent-lsd](https://npm.io/package/bittorrent-lsd.md) ^2.0.3
- [bittorrent-tracker](https://npm.io/package/bittorrent-tracker.md) ^11.2.3

## Recent versions

- 11.0.21 (latest) — 2026-05-25
- 11.0.20 — 2026-05-25
- 11.0.19 — 2025-09-14
- 11.0.18 — 2025-09-07
- 11.0.17 — 2025-05-14
- 11.0.16 — 2025-04-18
- 11.0.15 — 2025-01-20
- 11.0.14 — 2024-12-28
- 11.0.13 — 2024-12-07
- 11.0.12 — 2024-12-07
- 11.0.11 — 2024-09-07
- 11.0.10 — 2024-09-07
- 11.0.9 — 2024-08-13
- 11.0.8 — 2024-07-28
- 11.0.7 — 2024-07-09
- … 100 more at https://npm.io/package/torrent-discovery/versions

## README

# torrent-discovery [![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://github.com/webtorrent/torrent-discovery/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/webtorrent/torrent-discovery/actions/workflows/ci.yml
[npm-image]: https://img.shields.io/npm/v/torrent-discovery.svg
[npm-url]: https://npmjs.org/package/torrent-discovery
[downloads-image]: https://img.shields.io/npm/dm/torrent-discovery.svg
[downloads-url]: https://npmjs.org/package/torrent-discovery
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

### Discover BitTorrent and WebTorrent peers

This module bundles [bittorrent-tracker](https://www.npmjs.com/package/bittorrent-tracker), [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht), and [bittorrent-lsd](https://www.npmjs.com/package/bittorrent-lsd) clients and exposes a single API for discovering BitTorrent peers.

## features

- simple API
- find peers from trackers, DHT, and LSD
- automatically announces, so other peers can discover us
- can start finding peers with just an info hash, before full metadata is available

This module also **works in the browser** with [browserify](http://browserify.org). In
that context, it discovers [WebTorrent](http://webtorrent.io) (WebRTC) peers.

## install

```
npm install torrent-discovery
```

## api

### `discovery = new Discovery(opts)`

Create a new peer discovery instance. Required options are:

```js
{
  infoHash: '', // as hex string or Buffer
  peerId: '',   // as hex string or Buffer
  port: 0       // torrent client port (only required in node)
}
```

Optional options are:

```js
{
  announce: [],  // force list of announce urls to use (from magnet uri)
  dht: true,     // use dht? optionally, this can be an `opts` object, or a DHT instance to use (can be reused for multiple torrents)
  dhtPort: 0,    // custom listen port for the DHT instance (not used if DHT instance is given via `opts.dht`)
  userAgent: '', // User-Agent header for http requests
  tracker: true, // use trackers? optionally, this can be an `opts` object
  lsd: true      // use lsd?
}
```

See the documentation for [bittorrent-tracker](https://www.npmjs.com/package/bittorrent-tracker), [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht), and [bittorrant-lsd](https://www.npmjs.com/package/bittorrent-lsd) for information on what options are available via the `opts` object.

**This module automatically handles announcing on intervals, for maximum peer discovery.**

### `discovery.updatePort(port)`

When the port that the torrent client is listening on changes, call this method to
reannounce to the tracker and DHT with the new port.

### `discovery.complete([opts])`

Announce that download has completed (and the client is now a seeder). This is only
used by trackers, for statistical purposes. If trackers are not in use, then
this method is a no-op.

Optional `opts` object with the following options:

```
{number=} opts.uploaded
{number=} opts.downloaded
{number=} opts.numwant
{number=} opts.left (if not set, calculated automatically)
```

### `discovery.destroy()`

Destroy and cleanup the tracker, DHT, and LSD instances.

### events

### `discovery.on('peer', (peer, source) => {})`

Emitted whenever a new peer is discovered. Source is either `'tracker'`, `'dht'`, or `'lsd'` based on peer source.

**In node**, `peer` is a string in the form `ip:port`, e.g. `12.34.56.78:4000`.

**In the browser**, `peer` is an instance of
[`simple-peer`](https://www.npmjs.com/package/simple-peer), a small wrapper around a WebRTC
peer connection.

### `discovery.on('dhtAnnounce', () => {})`

Emitted whenever an `announce` message has been sent to the DHT.

### `discovery.on('warning', err => {})`

Emitted when there is a **non-fatal** tracker, DHT, or LSD error. For example, an
inaccessible tracker server would be considered a warning. Useful for logging.

### `discovery.on('error', err => {})`

Emitted when there is a fatal tracker, DHT, or LSD error. This is unrecoverable
and the `discovery` object will be destroyed if this event is emitted.

## license

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

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