Installation

Learn how to install WebTorrent in your Node.js or browser project

WebTorrent is available as an npm package and can be used in both Node.js and browser environments. This guide covers all installation methods.

Package Manager Installation

Install WebTorrent using your preferred package manager:

npm

npm install webtorrent

WebTorrent requires Node.js 16 or higher for server-side usage.

Browser Installation

Using a Bundler (Recommended)

If you’re using a module bundler like Webpack, Vite, or Rollup, simply import WebTorrent after installing it:

import WebTorrent from 'webtorrent'

const client = new WebTorrent()

Webpack Users: WebTorrent requires special webpack configuration. See the webpack bundle config used by WebTorrent for reference, or use the pre-built version below.

Using Pre-built Bundle

For webpack users or if you prefer to skip bundler configuration, use the pre-built version:

import WebTorrent from 'webtorrent/dist/webtorrent.min.js'

CDN Usage (ES Modules)

You can load WebTorrent directly from a CDN without any build step:

esm.sh

<script type="module">
  import WebTorrent from 'https://esm.sh/webtorrent/dist/webtorrent.min.js'
  
  const client = new WebTorrent()
  // Your code here
</script>

The CDN approach is perfect for quick prototypes and demos. For production apps, we recommend using a bundler for better optimization and caching.

Environment-Specific Setup

1. Browser Environment
2. WebTorrent uses WebRTC for peer-to-peer communication in the browser. Modern browsers support this out of the box:
4. Important: Browser-based WebTorrent clients can only connect to other WebRTC-enabled peers (“web peers”). They cannot connect to traditional BitTorrent peers using TCP/UDP.

5. Service Worker Setup (Required for Streaming)
6. To stream video and audio files in the browser, you need to set up a service worker:
8. const controller = await navigator.serviceWorker.register('./sw.min.js', { 
     scope: './' 
   })
   await navigator.serviceWorker.ready
   client.createServer({ controller })
   

9. Node.js Environment
10. In Node.js, WebTorrent uses TCP and UDP to communicate with other BitTorrent clients:
11. import WebTorrent from 'webtorrent'
    
    const client = new WebTorrent()
    

12. The standard webtorrent package in Node.js cannot connect to browser peers. To connect to both traditional peers AND browser peers, use webtorrent-hybrid instead.

13. Hybrid Mode (Node.js + WebRTC)
14. For Node.js applications that need to connect to browser peers:
15. npm install webtorrent-hybrid
    

16. import WebTorrent from 'webtorrent-hybrid'
    
    const client = new WebTorrent()
    // Can now connect to both traditional and web peers
    

Command Line Interface

WebTorrent also provides a command-line tool for downloading and streaming torrents:

npm install -g webtorrent-cli

Once installed, you can use the webtorrent command:

# Download a torrent
webtorrent "magnet:?xt=urn:btih:..."

# Stream to a media player
webtorrent "magnet:?xt=urn:btih:..." --vlc

WebTorrent Desktop

For a complete desktop application with a GUI, check out WebTorrent Desktop for Mac, Windows, and Linux.

Verify Installation

Test that WebTorrent is installed correctly:

Node.js

import WebTorrent from 'webtorrent'

const client = new WebTorrent()
console.log('WebTorrent version:', WebTorrent.VERSION)
console.log('WebRTC support:', WebTorrent.WEBRTC_SUPPORT)

Next Steps

Quick Start Guide

Learn the basics with working examples

API Reference

Explore the complete WebTorrent API