Guide · Open source
How to use WebTorrent: install, download and stream torrents
Updated · written with AI from the project's own documentation and checked against our catalogue data
WebTorrent is a BitTorrent client written entirely in JavaScript that runs in both Node.js and web browsers. It is aimed at developers who want to add torrent downloading or streaming to a web or Node.js app. After this guide you will know how to install the npm package, add a torrent to a client, seed files, and understand where browser peers can and cannot connect.
WebTorrentwebtorrent/webtorrent · ★ 31.5k · MIT Install options & downloads Quick start
- 1Check Node.js. WebTorrent requires Node.js. Make sure it is installed before you install the package.
- 2Install the package. Run npm install webtorrent in your project folder to add the library.
- 3Create a client. Import WebTorrent and create a new client with new WebTorrent().
- 4Add a magnet URI. Call client.add with a magnet URI and a callback that receives the torrent once its metadata is available.
- 5Read the files. Loop over torrent.files to access each file as a stream and display or process it.
- 6Seed your own files. Use client.seed with a list of files to create a torrent and start offering it to peers.
What WebTorrent is and who it is for
WebTorrent is a streaming torrent client for node.js and the browser. The same npm package works in both runtimes because it is written completely in JavaScript.
In Node.js it uses TCP and UDP to talk to other torrent clients. In the browser it uses WebRTC data channels for peer-to-peer transport and needs no plugins, extensions or installations.
- Good fit: developers adding torrent download or streaming to a JavaScript web or Node.js app.
- Good fit: web projects that need peer-to-peer file transfer without browser plugins.
- Not a fit: people who just want a ready-made torrent app. The README points to WebTorrent Desktop for that, since this repo is a library.
Install WebTorrent with npm
WebTorrent is installed with a package manager and requires Node.js. To use it as a library in Node or the browser with import WebTorrent from 'webtorrent', run the first command. To get the webtorrent command line program, install the separate webtorrent-cli package globally.
- Library: npm install webtorrent
- Command line program: npm install webtorrent-cli -g
npm install webtorrent
npm install webtorrent-cli -gDownload a torrent in the browser
Create a client, then call add with a magnet URI. The callback runs once the torrent metadata is available, and each entry in torrent.files can be listed on the page. The README leaves the magnet URI as a placeholder, so you supply your own.
You can also load the standalone webtorrent.min.js script with a script tag, or use browserify or webpack. Webpack needs extra configuration, or you can import the pre-built webtorrent/dist/webtorrent.min.js and skip it.
import WebTorrent from 'webtorrent'
const client = new WebTorrent()
const magnetURI = '...'
client.add(magnetURI, torrent => {
// Got torrent metadata!
console.log('Client is downloading:', torrent.infoHash)
for (const file of torrent.files) {
document.body.append(file.name)
}
})Seed files from the browser
Seeding means offering files to other peers. The README example uses the drag-drop package so that when a user drops files on the page, client.seed creates a new torrent and starts seeding it.
import dragDrop from 'drag-drop'
import WebTorrent from 'webtorrent'
const client = new WebTorrent()
// When user drops files on the browser, create a new torrent and start seeding it!
dragDrop('body', files => {
client.seed(files, torrent => {
console.log('Client is seeding:', torrent.infoHash)
})
})Stream video before the download finishes
WebTorrent exposes torrent files as streams. It fetches pieces on demand, so seeking works even before the torrent is finished, and it switches between sequential and rarest-first piece selection as needed. Video torrents can be streamed into a video tag.
Supported containers listed in the README include webm, mkv, mp4, ogv and mov, with codecs such as AV1, H264, VP8, VP9, AAC, MP3 and OPUS. Browsers listed as supported are Chrome, Firefox, Opera and Safari.
- Multiple torrents can be downloaded at the same time.
- Magnet URI support is provided through ut_metadata.
- Peer discovery uses DHT, trackers, LSD and ut_pex.
Use WebTorrent in Node.js and reach browser peers
WebTorrent also works in Node.js with the same npm package. The README notes that browser-based web peers can only connect to other clients that support WebTorrent/WebRTC. To connect to web peers in addition to normal BitTorrent peers, see the web-peer notes in the project's Node.js section.
To seed files to web peers, the README suggests a WebTorrent-capable client such as WebTorrent Desktop, webtorrent-hybrid, or the Instant.io website. Vuze has also added WebTorrent support.
- Browsers cannot reach standard UDP or TCP-only torrent clients directly.
What people use it for
- Adding torrent download to a Node.js service written in JavaScript.
- Sharing files peer-to-peer in a web app without asking users to install plugins.
- Streaming a video torrent into an HTML video tag while it is still downloading.
- Seeding files dropped onto a web page, using the drag-drop example from the README.
Frequently asked questions
How do I install WebTorrent?
Install the library with npm install webtorrent. For the command line program, run npm install webtorrent-cli -g. WebTorrent requires Node.js.
Is WebTorrent free to use?
The repository is licensed under MIT. The README does not describe pricing, and this guide does not claim anything beyond the licence.
Does WebTorrent need a browser plugin?
No. The README says WebTorrent uses WebRTC data channels in the browser and can be used without plugins, extensions, or installations.
Why can't my browser connect to my regular torrent client?
The README says browser-based web peers can only connect to other clients that support WebTorrent/WebRTC. Browsers cannot reach standard UDP or TCP-only torrent clients directly.
Is WebTorrent a ready-made torrent app?
No. This repository is a library. The README points to WebTorrent Desktop for a desktop application with a familiar UI.
How does WebTorrent compare to libtorrent, Transmission or qBittorrent?
WebTorrent is a pure JavaScript library that runs in Node.js and browsers and exposes files as streams. libtorrent, Transmission and qBittorrent are the other comparable projects listed for this item, and the choice depends on whether you are building into a JavaScript app or want a standalone client.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
WebTorrent is a good choice for developers who want torrent download or streaming inside a JavaScript web or Node.js app, especially without browser plugins. If you just want a torrent app to download files, or need browsers to reach standard torrent clients, choose WebTorrent Desktop or a classic client such as qBittorrent or Transmission instead.
Install options & downloads