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 .)
  • torrenttools (for creating torrents, optional)
  • 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.3

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.3
File Size Uploaded Provenance Actions
pptu-2026.11.3.tar.gz 69.3 kB Without provenance Details for pptu-2026.11.3.tar.gz

Built distribution (wheel)

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

Total release size: 153.1 kB

Release files / pptu-2026.11.3.tar.gz

Download URL pptu-2026.11.3.tar.gz
Size 69.3 kB
Tags Source
SHA-256 checksum
How to use checksums
28189546941c761f3534a7460d5b8024ee4dc02fe8cb2cc5ec38906a75ca71f8
BLAKE2b-256 checksum
How to use checksums
67580491479dfbca11502f6e9d438daf6c296c19e1a6815ebd3373069c147efe
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.3-py3-none-any.whl

Download URL pptu-2026.11.3-py3-none-any.whl
Size 83.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5cc4163b69ecc6e2b6ab1eeb7a53afb4d6b1e3ca480f982d9e1997fd47680f40
BLAKE2b-256 checksum
How to use checksums
1a243d0c644b6dad5dcd1ff7838d6783732b45115140da1fbc4a86b399db7ed6
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.3

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