Skip to main content

The Unofficial Pirate Bay Lightweight Python API

Project description

Unofficial Lightweight Python API for ThePirateBay

Build Status Coverage Status PyPI version


$ pip install tpblite


  • lxml


from tpblite import TPB

# Create a TPB object with a domain name
t = TPB('')

# Or create a TPB object with default domain
t = TPB()

N.B Before using you should check which ThePirateBay domain works for you, as this varies from country to country.


# Quick search for torrents, returns a Torrents object
torrents ='public domain')

# See how many torrents were found
print('There were {0} torrents found.'.format(len(torrents)))

# Iterate through list of torrents and print info for Torrent object
for torrent in torrents:

# Customize your search
from tpblite import CATEGORIES, ORDERS
torrents ='public domain', page=2, order=ORDERS.NAME.DES, category=CATEGORIES.VIDEO.MOVIES)

# Get the most seeded torrent based on a filter
torrent = torrents.getBestTorrent(min_seeds=30, min_filesize='500 MiB', max_filesize='4 GiB')

# Or select a particular torrent by indexing
torrent = torrents[3]

# Get the magnet link for a torrent


# You can browse all of the torrents from a single category
torrents = t.browse(category=CATEGORIES.VIDEO)
# Customize the page number and sort order
torrents = t.browse(category=CATEGORIES.VIDEO.MOVIES, page=1, order=ORDERS.UPLOADED.DES)


from tpblite import TPB, CATEGORIES
t = TPB()

# Get the top recent torrents 
torrents =

# Customize with category and restriction to torrents from the last 48h
torrents =, last_48=True)

Categories and Sort Order

# To print all available categories, use the classmethod printOptions
# Or just a subset of categories, like VIDEO
# Similarly for the sort order

Torrents object

The search function returns a Torrents object, which is a list-like collection of the torrents found.

You can also iterate over the Torrents object just by calling it in a for loop (see example above).

You can see how many Torrent objects your query has returned, by using the len() function

Torrent object

Torrent objects represent each torrent found in the Torrents class, they have the following attributes


  • Torrent.title - The name of the torrent (str)
  • Torrent.seeds - The number of seeders (int)
  • Torrent.leeches - The number of leechers (int)
  • Torrent.upload_date - Date the torrent was uploaded (str)
  • Torrent.uploader - Name of user who uploaded torrent (str)
  • Torrent.filesize - The filesize in *iB format, eg. 5 GiB (str)
  • Torrent.byte_size - The filesize in bytes of the torrent (int)
  • Torrent.magnetlink - magnetlink of the torrent (str)
  • Torrent.url - URL of the torrent page (str)
  • Torrent.is_trusted - Whether the torrent is from a trusted source.
  • Torrent.is_vip - Whether the torrent is from a VIP source.

Example Workflow

With a commandline torrent client such as aria2, you can automate search and downloading of torrents like so:

import subprocess
from tpblite import TPB

t = TPB()
torrents ='GIMP 2.10.8')
torrent = torrents.getBestTorrent()['aria2c', torrent.magnetlink])

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tpblite, version 0.7.1
Filename, size File type Python version Upload date Hashes
Filename, size tpblite-0.7.1-py3-none-any.whl (8.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size tpblite-0.7.1.tar.gz (8.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page