{"id":15934,"library":"webtorrent","title":"WebTorrent Client","description":"WebTorrent is a versatile streaming BitTorrent client designed for both Node.js environments and web browsers. Currently stable at version 2.8.5, it receives frequent minor updates and bug fixes, with new features introduced periodically. Its primary differentiator is its ability to operate directly within a web browser using WebRTC data channels for peer-to-peer communication, making it the \"streaming torrent client for the web.\" In Node.js, it functions as a standard torrent client utilizing TCP and UDP. This pure JavaScript library exposes torrent files as streams, supporting on-demand piece fetching, and can seamlessly switch between sequential and rarest-first piece selection strategies. WebTorrent facilitates connecting \"web peers\" (browser clients) with other WebTorrent-compatible clients, including desktop applications and specialized command-line tools like `webtorrent-hybrid`.","status":"active","version":"2.8.5","language":"javascript","source_language":"en","source_url":"git://github.com/webtorrent/webtorrent","tags":["javascript","bittorrent","bittorrent client","download","mad science","p2p","peer-to-peer","peers","streaming"],"install":[{"cmd":"npm install webtorrent","lang":"bash","label":"npm"},{"cmd":"yarn add webtorrent","lang":"bash","label":"yarn"},{"cmd":"pnpm add webtorrent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"WebTorrent v2.0+ is ESM-only; CommonJS `require()` is no longer supported.","wrong":"const WebTorrent = require('webtorrent')","symbol":"WebTorrent","correct":"import WebTorrent from 'webtorrent'"},{"note":"A static property to check WebRTC support in the current environment.","symbol":"WebTorrent.WEBRTC_SUPPORT","correct":"import WebTorrent from 'webtorrent'; const supportsWebRTC = WebTorrent.WEBRTC_SUPPORT"},{"note":"The `Torrent` class represents an active torrent download/seeding. It is usually obtained from a `WebTorrent` instance.","symbol":"Torrent","correct":"import WebTorrent, { Torrent } from 'webtorrent'; // or import type { Torrent } from 'webtorrent' for TS"}],"quickstart":{"code":"import WebTorrent from 'webtorrent';\nimport fs from 'node:fs';\n\nconst client = new WebTorrent();\n\nconst magnetURI = 'magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10'; // Example Sintel torrent (public domain)\n\nclient.add(magnetURI, { path: './downloads' }, (torrent) => {\n  console.log(`Client is downloading torrent: ${torrent.infoHash}`);\n\n  torrent.on('download', () => {\n    console.log(`Downloaded: ${torrent.downloaded} bytes of ${torrent.length} total`);\n  });\n\n  torrent.on('done', () => {\n    console.log('Torrent download finished!');\n    torrent.files.forEach((file) => {\n      console.log(`File name: ${file.name}, length: ${file.length}`);\n      // Example: Stream a file to disk (Node.js only)\n      const source = file.createReadStream();\n      const destination = fs.createWriteStream(`./downloads/${file.name}`);\n      source.pipe(destination);\n      source.on('end', () => {\n        console.log(`Finished writing ${file.name} to disk.`);\n      });\n    });\n    client.destroy(); // Clean up client after download\n  });\n\n  torrent.on('error', (err) => {\n    console.error('Torrent error:', err.message);\n    client.destroy();\n  });\n});\n\nclient.on('error', (err) => {\n  console.error('WebTorrent client error:', err.message);\n});","lang":"typescript","description":"This quickstart initializes a WebTorrent client, adds a magnet URI, logs download progress, and saves the torrent's files to a local directory once complete. It includes error handling and proper client cleanup."},"warnings":[{"fix":"Update imports to use ES module syntax: `import WebTorrent from 'webtorrent'`.","message":"WebTorrent v2.0+ is ESM-only. CommonJS `require()` syntax is no longer supported and will lead to errors in modern Node.js environments or bundled browser applications.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or higher.","message":"WebTorrent v2.0+ requires Node.js version 16 or later. Older Node.js versions (12, 14, etc.) are no longer supported and will cause runtime issues.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `await file.arrayBuffer()` to get an `ArrayBuffer` or `file.stream()` to get a `ReadableStream` instead.","message":"The `file.getBuffer()` method has been deprecated and removed in favor of standard Web APIs. Attempts to use it will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the torrent you are trying to download/seed in the browser is being seeded by a WebRTC-capable client (e.g., WebTorrent Desktop, Instant.io, webtorrent-hybrid).","message":"WebTorrent clients running in a web browser can only connect to other WebTorrent-compatible clients (known as 'web peers') that support WebRTC. They cannot directly connect to traditional BitTorrent clients using TCP or UDP, unless a 'hybrid' client acts as a bridge.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always call `torrent.destroy()` when you are finished with a torrent to clean up its associated storage.","message":"Starting with v2.0, WebTorrent in the browser uses persistent storage (File System Access API + IndexedDB) instead of memory-only. This means torrent data can persist across sessions but requires explicit cleanup to free up space.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the server hosting the .torrent file has `Access-Control-Allow-Origin` headers configured to permit requests from your domain.","cause":"This error often occurs in browser environments when trying to fetch a .torrent file from a URL without proper CORS (Cross-Origin Resource Sharing) headers from the server.","error":"Uncaught Error: Error downloading torrent: XHR error"},{"fix":"Verify that the torrent is being seeded by a client that supports WebTorrent/WebRTC (e.g., WebTorrent Desktop, instant.io).","cause":"In a browser, this typically means there are no WebRTC-compatible seeders for the given torrent. Traditional BitTorrent peers are not visible to browser clients.","error":"No peers found"},{"fix":"Double-check the magnet URI, info hash, or URL for correctness and ensure it adheres to the specified formats. For Node.js, file paths and Buffers are also accepted.","cause":"The input provided to `client.add()` does not match one of the supported torrent identifier formats.","error":"The torrent ID format is invalid. Supported formats: Magnet URI: magnet:?xt=urn:btih:... Info hash: 08ada5a7a6183aae1e09d831df6748d566095a10. HTTP URL to .torrent file: https://example.com/file.torrent. File path (Node.js only): /path/to/file.torrent. Buffer (Node.js only): Buffer containing .torrent file."},{"fix":"Ensure the target download directory (specified in `client.add({ path: './downloads' })`) has appropriate write permissions for the Node.js process. Try using a different, accessible directory or running the process with elevated privileges if necessary.","cause":"In Node.js, the WebTorrent client attempted to write downloaded files to a directory where the process lacks write permissions.","error":"Write to disk: access denied"}],"ecosystem":"npm"}