Skip to content

Getting Started

Getting Started

Welcome to ccBitTorrent! This guide will help you get up and running quickly with our high-performance BitTorrent client.

Key Feature: BEP XET Protocol Extension

ccBitTorrent includes the Xet Protocol Extension (BEP XET), which enables content-defined chunking and cross-torrent deduplication. This transforms BitTorrent into a super-fast, updatable peer-to-peer file system optimized for collaboration. Learn more about BEP XET →

Installation

Prerequisites

  • Python 3.8 or higher
  • UV package manager (recommended)

Install UV

Install UV from the official installation script: - macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh - Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install ccBitTorrent

Install from PyPI: 

uv pip install ccbittorrent

Or install from source: 

git clone https://github.com/yourusername/ccbittorrent.git
cd ccbittorrent
uv pip install -e .

Entry points are defined in pyproject.toml:79-81.

Main Entry Points

ccBitTorrent provides three main entry points:

Bitonic is the main terminal dashboard interface. It provides a live, interactive view of all torrents, peers, and system metrics.

See Bitonic Guide for detailed usage.

2. btbt CLI

btbt is the enhanced command-line interface with rich features.

See btbt CLI Reference for all available commands.

3. ccbt (Basic CLI)

ccbt is the basic command-line interface.

Quick Start

Start the terminal dashboard: 

uv run bitonic

Or via the CLI: 

uv run ccbt dashboard

With custom refresh rate: 

uv run ccbt dashboard --refresh 2.0

Download a Torrent

Using the CLI: 

# Download from torrent file
uv run btbt download movie.torrent

# Download from magnet link
uv run btbt magnet "magnet:?xt=urn:btih:..."

# With rate limits
uv run btbt download movie.torrent --download-limit 1024 --upload-limit 512

See btbt CLI Reference for all download options.

Configure ccBitTorrent

Create a ccbt.toml file in your working directory. Reference the example configuration: - Default config: ccbt.toml - Environment variables: env.example - Configuration system: ccbt/config/config.py

See Configuration Guide for detailed configuration options.

Project Reports

View project quality metrics and reports:

These reports are automatically generated and updated as part of our continuous integration process.

Next Steps

Getting Help