Configuration Options

Complete reference for WebTorrent configuration options

Client Options

Options passed to the WebTorrent constructor:

const client = new WebTorrent({
  maxConns: 100,
  dht: true,
  tracker: true
  // ... more options
})

Connection Settings

maxConns · number · default: 55

Maximum number of connections per torrent

seedOutgoingConnections · boolean · default: true

If true, establish outgoing connections while seeding. If false, only respond to incoming connections when seeding.

Identity Settings

peerId · string | Uint8Array

Wire protocol peer ID (default: randomly generated). Must be 20 bytes.

nodeId · string | Uint8Array

DHT protocol node ID (default: randomly generated). Must be 20 bytes.

Discovery Settings

tracker · boolean | object · default: true

Enable tracker support. Can be:

• true - Enable with default options
• false - Disable tracker support
• object - Enable with custom options (see bittorrent-tracker docs)

If an object, can include:

• announce - Array of tracker URLs to add to all torrents
• wrtc - Custom WebRTC implementation

new WebTorrent({
  tracker: {
    announce: ['wss://tracker.example.com'],
    wrtc: customWRTC
  }
})

dht · boolean | object · default: true

Enable DHT support. Can be:

• true - Enable with default options
• false - Disable DHT
• object - Enable with custom options (see bittorrent-dht docs)

lsd · boolean · default: true

Enable BEP14 local service discovery

utPex · boolean · default: true

Enable BEP11 Peer Exchange

webSeeds · boolean · default: true

Enable BEP19 web seeds

Network Settings

utp · boolean · default: true

Enable BEP29 uTorrent transport protocol (Node.js only)

natUpnp · boolean | string · default: true

Enable NAT port mapping via UPnP (Node.js only). Can be:

• true - Use temporary mapping
• 'permanent' - Use permanent TTL if router only supports permanent leases
• false - Disable UPnP

natPmp · boolean · default: true

Enable NAT port mapping via NAT-PMP (Node.js only). If both natUpnp and natPmp are true, PMP is attempted first, then falls back to UPnP.

torrentPort · number · default: 0

Port for incoming torrent connections (Node.js only). 0 = random port.

dhtPort · number · default: 0

Port for DHT (Node.js only). 0 = random port.

Bandwidth Settings

downloadLimit · number

Maximum download speed in bytes/sec for all torrents. Can be:

• > 0 - Set throttle at that speed
• 0 - Block all downloads
• -1 - Disable throttling (use full bandwidth)

uploadLimit · number

Maximum upload speed in bytes/sec for all torrents. Can be:

• > 0 - Set throttle at that speed
• 0 - Block all uploads
• -1 - Disable throttling (use full bandwidth)

new WebTorrent({
  downloadLimit: 1000000, // 1 MB/s
  uploadLimit: 500000     // 500 KB/s
})

Security Settings

blocklist · Array<string> | string

List of IP addresses to block. Can be:

• Array of IP ranges
• URL to a blocklist file

See load-ip-set docs for details.

new WebTorrent({
  blocklist: [
    '1.2.3.4',
    '5.6.7.8/16'
  ]
})

secure · boolean · default: false

Enable secure peer connections (experimental)

Torrent Options

Options passed to client.add() or client.seed():

client.add(magnetURI, {
  path: '/downloads',
  maxWebConns: 4
  // ... more options
})

Discovery Options

announce · Array<string>

Additional tracker URLs to use (added to those in .torrent or magnet URI)

client.add(magnetURI, {
  announce: [
    'wss://tracker1.example.com',
    'wss://tracker2.example.com'
  ]
})

getAnnounceOpts · function

Custom callback to send extra parameters to trackers

client.add(magnetURI, {
  getAnnounceOpts: () => ({
    numwant: 50,
    key: 'custom-key'
  })
})

urlList · Array<string>

Array of web seed URLs (BEP19)

maxWebConns · number · default: 4

Maximum number of simultaneous connections per web seed

private · boolean

If true, client will not share the hash with DHT or PEX. Default is the privacy setting from the torrent.

Storage Options

path · string · default: "/tmp/webtorrent/"

Folder to download files to

addUID · boolean · default: false

(Node.js only) If true, store files in an infoHash subfolder to prevent name collisions

// Files saved to: /downloads/<infoHash>/filename
client.add(magnetURI, {
  path: '/downloads',
  addUID: true
})

rootDir · FileSystemDirectoryHandle

(Browser only) Custom directory handle for File System Access API. Retains torrent folder structure.

store · Function

Custom chunk store constructor. Must follow abstract-chunk-store API.

import MemoryChunkStore from 'memory-chunk-store'

client.add(magnetURI, {
  store: MemoryChunkStore
})

preloadedStore · Function

Pre-loaded chunk store instance

storeOpts · object

Custom options passed to the store constructor

storeCacheSlots · number · default: 20

Number of pieces to cache in memory. Set to 0 to disable caching.

destroyStoreOnDestroy · boolean · default: false

If true, delete files from disk when torrent is destroyed

Download Options

strategy · 'rarest' | 'sequential' · default: "sequential"

Piece selection strategy

skipVerify · boolean · default: false

If true, skip verification of existing pieces and assume they’re correct

bitfield · Uint8Array

Pre-loaded bitfield indicating which pieces are already downloaded

client.add(magnetURI, {
  skipVerify: true,
  bitfield: existingBitfield
})

paused · boolean · default: false

If true, create the torrent in a paused state

deselect · boolean · default: false

If true, create the torrent with no pieces selected

Upload Options

uploads · number | false · default: 10

Maximum number of upload slots. Set to false or 0 to disable uploading.

alwaysChokeSeeders · boolean · default: true

If true, automatically choke seeders when seeding

Advanced Options

noPeersIntervalTime · number · default: 30

Time in seconds to wait between noPeers event checks

fileModtimes · Array<number>

Array of UNIX timestamps indicating last modification time for each file. Used to skip verification if files haven’t changed.

Seed Options

Options passed to client.seed() include all torrent options plus create-torrent options:

Torrent Creation

name · string

Name of the torrent. If not provided, determined automatically from file names.

comment · string

Comment to include in the torrent

createdBy · string · default: "WebTorrent/<version>"

Creator/editor of the torrent

creationDate · Date | number

Creation date (default: now)

pieceLength · number

Piece length in bytes (default: auto-calculated)

private · boolean · default: false

If true, don’t announce on DHT or allow PEX

info · object

Additional info dict fields

client.seed(files, {
  name: 'My Torrent',
  comment: 'Created with WebTorrent',
  private: true,
  announce: ['wss://tracker.example.com']
}, torrent => {
  console.log('Seeding:', torrent.magnetURI)
})

For more create-torrent options, see create-torrent docs.