Skip to main content


Python P2P Torrent Uploader

Requirements

  • Python 3.10 to 3.13
  • Python package dependencies (uv sync --frozen – requires uv 0.8.0 or newer – or pip install .)
  • mkbrr or intermodal (imdl) (faster torrent creation, optional; torf is used by default)
  • cfsolve (for headless Cloudflare solving, optional)
  • MediaInfo CLI (for generating tech info)
  • FFmpeg (for generating snapshots)

Supported trackers

Name Acronym Auth Protection Captcha Server upload allowed
General
BroadcasTheNet BTN Credentials/
Cookies
None No Dedicated servers only, requires staff approval
HDBits HDB Credentials/
Cookies
Cloudflare Simple Yes, if IP whitelisted in profile or 2FA enabled
nCore nC Credentials/
Cookies
None No Yes
nekoBT nBT API key None No Yes
Nyaa nyaa Credentials DDoS-Guard No Yes
PassThePopcorn PTP Credentials/
Cookies
None No Dedicated servers only, requires staff approval
AvistaZ Network
AvistaZ AvZ Credentials/
Cookies
None Yes Yes, if IP whitelisted in profile
CinemaZ CZ
PrivateHD PHD

For sites with captcha, a 2captcha API key is required to solve the captcha. Manual solving may be added in the future. "Simple" captchas can be solved automatically without 2captcha or user interaction.

PassThePopcorn

  • Credential auth requires passkey in addition to username and password.

Cloudflare-protected trackers

Some trackers (currently HDBits) sit behind a Cloudflare managed challenge. The challenge yields a cf_clearance cookie that is bound to your IP, User-Agent, and TLS fingerprint. Settings go in the tracker's own config section ([hdbits] below).

By default (cf_solver = "auto"), pptu tries the headless cfsolve solver first, and automatically falls back to the real browser solver (nodriver) or manual cookies if needed. You can skip cfsolve and force the real browser solver at any time by setting cf_solver = "browser" (or cfsolve = false) under [hdbits] in config.toml, or passing --cf-solver browser on the command line.

Primary: headless solver via cfsolve (no browser or GUI needed)

  • Install cfsolve (requires cmake and libclang, e.g. sudo dnf install cmake clang-devel on Fedora or sudo apt install cmake libclang-dev on Debian/Ubuntu):
    cargo install --git https://github.com/chris124567/cfsolve --bin challenge
    
  • No config paths are needed: pptu automatically finds the challenge binary on your PATH (or ~/.cargo/bin) and automatically downloads and caches the browser profile into ~/.local/share/pptu/cfsolve/profiles/ on first use.
  • If cfsolve fails or its clearance is rejected, pptu automatically falls back to the browser solver or manual cookies below.

Fallback 1: built-in browser solver (desktop with a GUI)

  • Install the extra: pip install 'pptu[cloudflare]' (or pip install nodriver). It needs Chrome, Chromium, Edge or Brave installed.
  • pptu briefly opens the browser, clears the check, and stores the clearance and the browser's User-Agent next to the tracker's cookies. Later runs reuse them until they expire.
  • If the browser isn't auto-detected, set browser_path (e.g. /snap/bin/chromium, /Applications/Google Chrome.app/Contents/MacOS/Google Chrome or C:\Program Files\Google\Chrome\Application\chrome.exe).
  • On a Linux server with a browser but no display, run xvfb-run pptu ....
  • If Cloudflare shows a "Verify you are human" checkbox, click it in the opened window. For unattended runs (--auto, watch folders), set 2captcha_api_key (the same key AvistaZ uses) instead: when the browser hasn't passed after 15 seconds, pptu has 2captcha solve the Turnstile check and hands the token back to the page, so no click is needed.

Fallback 2: exported cookies (headless / CLI-only servers without cfsolve)

  1. On a machine with a browser on the same network (same IP / VPN exit), pass the check on the tracker's site and export its cookies as Netscape cookies.txt (must include cf_clearance).
  2. Save them as the tracker's cookie file in pptu's cookies directory (~/.local/share/pptu/cookies/ on Linux): <tracker>.txt (e.g. hdb.txt), or <tracker>_<sha1 of your username>.txt if a username is set. No username or password is needed for this.
  3. Tell pptu that browser's exact User-Agent, because a mismatch gets the clearance rejected:
    [hdbits]
    browser_ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... Chrome/131.0.0.0 Safari/537.36"
    

When run interactively without a solver, pptu prints the cookie file path, waits for you to drop the file in, and asks for the User-Agent, so steps 2 and 3 can be done on the spot.

AvistaZ Network

  • Using credential auth is strongly recommended as cookies always expire within a few days.

Installation

Install dependencies and the script with ./install.py. You can re-run the script to update after a git pull.

Setup

Copy config.example.toml to ~/.config/pptu/config.toml and edit it as appropriate.

For credential-based auth, add your credentials in ~/.config/pptu/config.toml:

[TRACKER]
username = "yourusername"
password = "yourpassword"

Optionally, you may specify totp_secret for automating 2FA logins. Optionally, you may specify img_uploader for image host site.

For cookie-based auth, place cookies in ~/.local/share/pptu/cookies/TRACKER.txt.

TRACKER is the name or the abbreviation of the tracker above (all lowercase).

Usage

❯ pptu -h

Usage: pptu [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options:
   -v, --version                      Show the version and exit.
   -i, --input PATH                   Files or directories to create torrents for.
   --fast-upload / --no-fast-upload   Upload only after all steps succeed (or force-disable).
   -c, --confirm                      Ask for confirmation before uploading.
   -a, --auto                         Run non-interactively (never prompt).
   --cf-solver [auto|browser|...]     Cloudflare solver: auto, browser, cfsolve, manual.
   -ds, --disable-snapshots           Skip creating description snapshots.
   -s, --skip-upload                  Create torrents but don't upload.
   -n, --note TEXT                    Note to attach to the upload.
   -lt, --list-trackers               Show the list of supported trackers and exit.
   -h, --help                         Show this message and exit.

Uploaders (9):
   AvistaZ          https://avistaz.to/
   BroadcasTheNet   https://broadcasthe.net/
   CinemaZ          https://cinemaz.to/
   HDBits           https://hdbits.org/
   nCore            https://ncore.pro/
   nekoBT           https://nekobt.to/
   Nyaa             https://nyaa.si/
   PassThePopcorn   https://passthepopcorn.me/
   PrivateHD        https://privatehd.to/

Example

pptu -i /path/example.mkv -i /path/example2.mkv hdb nc --request-id 12356

Metadata

Release files for pptu 2026.11.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pptu 2026.11.14
File Size Uploaded Provenance Actions
pptu-2026.11.14.tar.gz 70.3 kB Without provenance Details for pptu-2026.11.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pptu 2026.11.14
File Interpreter ABI Platform Actions
pptu-2026.11.14-py3-none-any.whl Python 3 none any Details for pptu-2026.11.14-py3-none-any.whl

Total release size: 154.8 kB

Release files / pptu-2026.11.14.tar.gz

Download URL pptu-2026.11.14.tar.gz
Size 70.3 kB
Tags Source
SHA-256 checksum
How to use checksums
768f4a502b1cea5d97dd1efc0224db0a2816d1bbec7e7b05982ee1f70b6a3dea
BLAKE2b-256 checksum
How to use checksums
7ac31d54a52492b1d071a5cb36ad827bf3badc53b027ae03094b3f0d18e1e324
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / pptu-2026.11.14-py3-none-any.whl

Download URL pptu-2026.11.14-py3-none-any.whl
Size 84.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
10599a3b5bd1033b01df85f8e53c68721a7314b78aeb96bc3b861e7d597554dd
BLAKE2b-256 checksum
How to use checksums
a1ff1ef7f15ae03d9f097e4a91001b7a0be7060e703cc38c1f73c45da9e87c35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for pptu 2026.11.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page