tribler Documentation

Privacy enhanced BitTorrent client with P2P content discovery

5,227 stars Python Python 1 file · ~4,544 tokens #bittorrent#decentralized#p2p#privacy#python#search#streaming#tor
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy tribler on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name tribler --restart always ghcr.io/tribler/tribler:latest
Configured Services & Ports
⚙️ tribler
image: ghcr.io/tribler/tribler:latest
docker-compose.yml
yaml (docker-compose.yml) 
services:
  tribler:
    image: ghcr.io/tribler/tribler:latest
    security_opt:
      - apparmor:unconfined  # Not ideal, but allows DBUS communication TO host from the container (see "dirty hack")
    environment:
      - LANG=C.UTF-8
      # DBUS/Xorg stuff
      - DISPLAY=$DISPLAY
      - DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS
      - XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR
      - XAUTHORITY=$XAUTHORITY
      - XDG_CACHE_HOME=$XDG_CACHE_HOME
      # Dirty hack to forward org.freedesktop.portal.Desktop DBUS to host
      - BROWSER=x-www-browser
      # Tribler settings
      - CORE_API_PORT=8085
      - CORE_API_KEY=changeme
    network_mode: host
    volumes:
      # Tray icons
      - $XDG_CACHE_HOME/tmp/:/tmp
      # Xorg stuff
      - /run:/run
      # Tribler directories
      - ~/.Tribler:/state
      - ~/downloads/TriblerDownloads:/downloads
    user: $(id -u):$(id -g)

File: doc/basics/docker.rst

Running Tribler in Docker

In order to run Tribler from docker you only need a few steps.
We assume you have docker installed.

Currently, only running the (unstable!) latest release is supported.

Preparation

Fetch the docker image from docker.io:

.. code-block::

text
docker pull tribler/tribler:latest

Or, from ghcr.io:

.. code-block::

text
docker pull ghcr.io/tribler/tribler:latest

Running

Choose a SECRET key for the background communication with Tribler.
In the following example, we use the key changeme (don't use this yourself).
To run the docker image:

.. code-block::

text
docker run -e CORE_API_PORT=8085 -e CORE_API_KEY="changeme" \
           -e LANG=C.UTF-8 \
           -v ~/.Tribler:/home/ubuntu/.Tribler \
           -v ~/downloads/TriblerDownloads:/home/ubuntu/Downloads \
           -v $XDG_CACHE_HOME/tmp/:$XDG_CACHE_HOME/tmp/ -v /run:/run \
           --security-opt "apparmor:unconfined" \
           --net="host" \
           -e XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR -e DISPLAY=$DISPLAY \
           -e XDG_CACHE_HOME=$XDG_CACHE_HOME -e XAUTHORITY=$XAUTHORITY \
           -e DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" \
           --user $(id -u):$(id -g) -e BROWSER="x-www-browser" \
           -it ghcr.io/tribler/tribler:latest

Alternatively, if you want to run without opening the web GUI and without a tray icon:

.. code-block::

text
docker run -e CORE_API_PORT=8085 -e CORE_API_KEY="changeme" \
           -e LANG=C.UTF-8 \
           -v ~/.Tribler:/home/ubuntu/.Tribler \
           -v ~/downloads/TriblerDownloads:/home/ubuntu/Downloads \
           --net="host" -it ghcr.io/tribler/tribler:latest -s

You can then open Tribler in your web browser at the URL:

.. code-block::

text
localhost:8085/ui/#/downloads/all?key=changeme

Notes

This script binds the local "state" directory (this is where Tribler puts its internal files) to ~/.Tribler and your downloads directory (where your downloads end up) to ~/downloads/TriblerDownloads.
You can change these directories if you want to.

If you're planning on manipulating Tribler's internal REST API, you can access it through http://localhost:8085/docs.
By default, the REST API is bound to localhost inside the container so to
access the APIs, network needs to be set to host (--net="host").

Stopping

To stop Tribler, you should get the container id of your process and then stop it.
You can view all active docker containers using docker ps and you can stop a container id using docker stop.
For most UNIX systems, the following command will stop your Tribler Docker container:

.. code-block::

text
docker stop $(docker ps -aqf ancestor="ghcr.io/tribler/tribler:latest")

File: doc/basics/running.rst

Running Tribler from Source

In order to run Tribler from its source you will need to perform some setup.
We assume you have git and python installed.
If you want to run a GUI for Tribler, you will need npm installed too.

Steps

  1. Clone the Tribler repo:

.. code-block::

text
git clone --recursive https://github.com/tribler/tribler

.. warning::
Tribler uses submodules.
If you (1) download the ZIP or (2) forget to recursively clone, your pyipv8 folder will be empty.
Repair the former by downloading the IPv8 zip <https://github.com/Tribler/py-ipv8>_ and extracting it in the pyipv8 folder and repair the latter by running git submodule update --init.

  1. Install the python dependencies:

.. code-block::

text
python -m pip install --upgrade -r tribler/requirements.txt
  1. Build the GUI:

.. code-block::

text
cd src/tribler/ui/
npm install
npm run build

  1. Add the IPv8 submodule to your PYTHONPATH. For example, (Windows) set PYTHONPATH=%PYTHONPATH%;pyipv8, (Linux) export PYTHONPATH="${PYTHONPATH}:pyipv8" or (PyCharm) right click the pyipv8 folder and Mark Directory as/Sources Root.

  2. Run Tribler:

.. code-block::

text
cd src
python run_tribler.py

Sometimes, you may run into platform-specific issues.
If this is your case, continue reading for your appropriate platform.

File: doc/building/linux.rst

Building on Linux

We assume you've set up your environment to run Tribler.
Don't forget to build the GUI using NPM!
Run the following commands in your terminal (assuming you are in the Tribler's repository root folder).

First, install additional requirements:

.. code-block::

text
sudo apt-get -y install alien devscripts fakeroot gir1.2-gtk-3.0 libgirepository1.0-dev rpm libcairo2-dev patchelf
python -m pip install --upgrade -r build/requirements.txt

Second, create the .deb file in the dist directory.
You can set the GITHUB_TAG to whatever you want to have your version set as.

.. code-block::

text
export GITHUB_TAG="1.2.3"

./build/debian/makedist_debian.sh

File: doc/building/mac.rst

Building on Mac

We assume you've set up your environment to run Tribler.
Don't forget to build the GUI using NPM!
Run the following commands in your terminal (assuming you are in the Tribler's repository root folder).

First, install additional requirements:

.. code-block::

text
python -m pip install -r build/requirements.txt

Second, create the .dmg file in the dist directory.
You can set the GITHUB_TAG to whatever you want to have your version set as.

.. code-block::

text
export GITHUB_TAG="1.2.3"

./build/mac/makedist_macos.sh

File: doc/building/windows.rst

Building on Windows

We assume you've set up your environment to run Tribler.
Don't forget to build the GUI using NPM!
Additionally, you will need to install:

  • NSIS, the SimpleFC plugin, and the nsProcess plugin.
  • Microsoft Visual Studio 2022 Enterprise. 2022 Community will also work, but you need to edit tribler.nsi in the appropriate place.
  • Windows Kits 10.0.26100.0.
  • OpenSSL.

.. note::
If you install any of these applications to non-default folders, you will need to modify the build scripts.

Run the following commands in your command prompt (assuming you are in the Tribler's repository root folder).

First, install additional requirements:

.. code-block::

text
python -m pip install -r build/requirements.txt

Second, create the .exe file in the dist directory.
You can set the GITHUB_TAG to whatever you want to have your version set as.

.. code-block::

text
set GITHUB_TAG="1.2.3"

build\win\makedist_win.bat

File: doc/reference/software_architecture.rst

Software Architecture

This reference provides a high-level overview of Tribler's software architecture.

The main entry point of Tribler is the run_tribler.py script and it has two main modes.
The first mode launches Tribler with default settings.
This causes a new browser tab to open that displays a web page generated with TypeScript.
The second "headless" mode, does not open a browser tab.
However, in both modes the core Tribler Python process runs.

An overview of the most important functional components of Tribler is given in the following graph.
We will provide a short description of each of these components.

.. figure:: software_architecture.svg

Session

The Session object (in session.py) manages the core managers of Tribler:

  • The Notifier allows components to publish and subscribe to events.
    In some special cases, this is preferred over class inheritance or composition.
    Architectural spaghetti can sometimes be avoided by using Notifier events.
  • The TriblerConfigManager manages writing to and reading from user configuration files.
    This class manages defaults and the regeneration of (partially) missing configurations.
  • The DownloadManager allows management of torrent downloads.
    Functionality involves fetching torrent meta information, adding and removing downloads, and changing their anonymity level.
  • The RESTManager sets up a REST API.
    The API is used by Tribler's GUI, but can also be used programmatically by users in "headless" mode.
  • IPv8 is used to manage peer-to-peer network overlays.
    All peer-to-peer traffic is handled by IPv8 with the exception of non-anonymized torrent downloads.
    Functionality involves decentralized search and sharing popular torrents.
  • The IPv8CommunityLoader is used to launch all optional parts of Tribler.
    This includes launching IPv8 overlays and registering REST API endpoints.

The TriblerDatabase, MetadataStore and the TorrentChecker are optionally available through the Session.
If requested, they are launched through the IPv8CommunityLoader.

Components

The optional components of Tribler are given in components.py.
They can be divided into two groups: those that require a network overlay (inheriting from ComponentLauncher) and those that do not (inheriting from ComponentLauncher).
Furthermore, the components can have complex relationships, like only launching after other components.

The following list contains a high-level description of the components:

  • The DatabaseComponent is responsible for the two main databases.
    The first is the MetadataStore, which stores all torrent and torrent tracker meta data and "health" (seeders and leechers).
    The second is the TriblerDatabase, which stores torrent tags.
  • The TorrentCheckerComponent is responsible for retrieving the "health" information of torrents and trackers.
    This component may contact trackers for random torrents to determine whether they are reachable.
    The component also periodically updates the health information for known torrents based on tracker and DHT information.
  • The VersioningComponent is responsible for Tribler version management.
    Functionality includes upgrading data from local old Tribler versions to new Tribler versions and determining whether a new Tribler version has been published online.
  • The TunnelComponent allows for anonymization of torrent downloads.
    This component manages routing downloads over Tor-like circuits, including circuit construction and destruction.
  • The DHTDiscoveryComponent allows IPv8 to decentrally search for overlays and peers with given public keys.
  • The ContentDiscoveryComment serves remote user searches and content popularity.
    Both outgoing and incoming user searches are served through this component.
  • The KnowledgeComponent handles extraction and search for torrent tags.
  • The RendezvousComponent keeps track of peers that have been connected to in the past.
    This is an experimental component that aims to serve as a source of decentral reputation.
  • The RecommenderComponent keeps track of local user searches and the preferred download for the search query.
    This is an experimental component that aims to serve as a source for Artificial Intelligence based personalized recommendations.

Web UI

The Web UI serves to view and control the state of the Tribler process.
Essentially, the Web UI uses three main classes:

  • The IPv8Service binds to the REST API of the IPv8 component in the Tribler process.
  • The TriblerService binds to the REST API of anything that is not in the IPv8 service.
  • The App is the React application entrypoint.

The App contains a component to route information, the RouterProvider, and a means to report errors that have been sent from the Tribler process.
The architecture closely resembles the information in the GUI.
Essentially, the RouterProvider mirrors the visible pages:

  • src/pages/Debug queries the Tribler process for debug information.
  • src/pages/Downloads includes components to render torrent downloads.
  • src/pages/Popular queries for popular torrents.
  • src/pages/Search manages pending searches, combining local and remote results.
  • src/pages/Settings reads and writes the Tribler configuration (through the REST API).

File: doc/index.rst

.. note::
Looking for user documentation? Check out https://www.tribler.org/howto.html

Welcome to Tribler's developer documentation!

Tribler aims to give anonymous access to content. We are trying to make privacy, strong cryptography, and authentication the Internet norm.

These documents specify how to run Tribler from the latest source code and how to build Tribler distributions.

Table of contents

.. toctree::
:maxdepth: 2
:caption: Basics:

basics/running.rst
basics/docker.rst

.. toctree::
:maxdepth: 2
:caption: Building:

building/linux.rst
building/mac.rst
building/windows.rst

.. toctree::
:maxdepth: 2
:caption: Reference:

reference/software_architecture.rst

  • :ref:genindex
  • :ref:modindex
  • :ref:search

File: src/tribler/ui/README.md

Tribler web UI

Getting started

After checking out the Tribler repo, the web UI will not run out-of-the box. You'll either have to build the web UI or serve it from the Vite development server.

Building the web UI works as follows:

text
cd src/tribler/ui/
npm install
npm run build

This will create a dist folder which will automatically be served after Tribler restarts.

Alternatively, while working on the web UI, it's often more convenient use the development server:

text
cd src/tribler/ui/
rm dist -r
npm install
npm run dev

After restarting Tribler, requests to /ui will be forwarded to the development server. Tribler assumes that the development server will run at http://localhost:5173.

File: README.rst

|doi| |openhub|
|python_3_12| |contributors| |pr_closed| |issues_closed|

|
|

.. raw:: html

|

Alternative downloads:

  • flathub <https://flathub.org/apps/org.tribler.Tribler>_ |flathub|

    .. raw:: html

    text
    <small>For Fedora ≥ 42 and pure GNOME check out [this tray icon guide](https://github.com/Tribler/tribler/wiki/Enabling-the-Tray-icon-on-pure-GNOME).</small>

|

Tribler

Towards making Bittorrent anonymous and impossible to shut down.

Tribler aims to give anonymous access to content. We are trying to make privacy, strong cryptography, and authentication the Internet norm.

We implemented our own enhanced Tor-like network for anonymous torrent downloading <https://github.com/Tribler/tribler/wiki/Anonymous-Downloading-and-Streaming-specifications>_, with hidden services based
seeding and end-to-end encryption.

Since 2004, we have been working to ensure that "the only way to take Tribler down is to take The Internet down" (but a single software bug could end everything).

Socials, Support and Contribution

Want to hang out with other Tribler users?

  • Join our |discord| !

Have you found a bug or do you have a feature request?

  • If nobody else has already, open an issue <https://github.com/Tribler/tribler/issues/new>_!

Lost in development?

  • Check out our |docs| for development and building instructions!

|

| |downloads_pre_2006| |downloads_sourceforge| |downloads_github|
| |latest_badge| |downloads_latest|

License

This file is part of Tribler, Copyright 2004-2024. Tribler is licensed under the GNU General Public License, version 3 (GPL-3.0), as published by the Free Software Foundation on 29 June 2007. Tribler is free software: you can redistribute it and/or modify it under the terms of this license. Tribler is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. For more details, see the full terms and conditions in the LICENSE.txt <LICENSE.txt>_ file at the root of this repository, or visit https://www.gnu.org/licenses/gpl-3.0.html.

.. |pr_closed| image:: https://img.shields.io/github/issues-pr-closed/tribler/tribler.svg?style=flat
:target: https://github.com/Tribler/tribler/pulls
:alt: Pull Requests

.. |issues_closed| image:: https://img.shields.io/github/issues-closed/tribler/tribler.svg?style=flat
:target: https://github.com/Tribler/tribler/issues
:alt: Issues

.. |openhub| image:: https://www.openhub.net/p/tribler/widgets/project_thin_badge.gif?style=flat
:target: https://www.openhub.net/p/tribler

.. |downloads_pre_2006| image:: https://img.shields.io/badge/total_downloads_pre_2006-1.8M-brightgreen

.. |downloads_sourceforge| image:: https://img.shields.io/badge/total_downloads_SourceForge-200k-brightgreen
:target: https://sourceforge.net/projects/tribler/

.. |downloads_github| image:: https://img.shields.io/github/downloads/Tribler/tribler/total?label=total%20downloads%20GitHub
:target: https://github.com/Tribler/tribler/releases

.. |latest_badge| image:: https://img.shields.io/github/v/release/Tribler/tribler?label=latest&color=orange

.. |downloads_latest| image:: https://img.shields.io/github/downloads/Tribler/tribler/latest/total?color=orange
:target: https://github.com/Tribler/tribler/releases

.. |contributors| image:: https://img.shields.io/github/contributors/tribler/tribler.svg?style=flat
:target: https://github.com/Tribler/tribler/graphs/contributors
:alt: Contributors

.. |doi| image:: https://zenodo.org/badge/8411137.svg
:target: https://zenodo.org/badge/latestdoi/8411137
:alt: DOI number

.. |docs| image:: https://readthedocs.org/projects/tribler/badge/?version=latest
:target: https://tribler.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. |discord| image:: https://img.shields.io/badge/discord-join%20chat-blue.svg
:target: https://discord.gg/UpPUcVGESe
:alt: Join Discord chat

.. |python_3_12| image:: https://img.shields.io/badge/python-3.12-blue.svg
:target: https://www.python.org/

.. |flathub| image:: https://img.shields.io/flathub/downloads/org.tribler.Tribler
:alt: Flathub Downloads

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#bittorrent Browse bittorrent catalog → #decentralized Browse decentralized catalog → #p2p Browse p2p catalog → #privacy Browse privacy catalog → #python Browse python catalog → #search Browse search catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →