Metadata-Version: 2.4
Name: quickdownload
Version: 1.5.0
Summary: High-performance parallel file downloader with multi-device cluster support, queue system, bandwidth throttling, and torrent support
Author-email: Nikhil K Singh <nsr.nikhilsingh@gmail.com>
License: MIT
Project-URL: homepage, https://github.com/Nikhil-K-Singh/quickdownload
Keywords: download,parallel,torrent,resume,cli,http,https,magnet,cluster,multi-device,queue,throttling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: libtorrent==2.0.11
Requires-Dist: requests==2.31.0
Dynamic: license-file

# QuickDownload

![PyPI Version](https://img.shields.io/pypi/v/quickdownload)
![Python Support](https://img.shields.io/pypi/pyversions/quickdownload)
![License](https://img.shields.io/github/license/Nikhil-K-Singh/quickdownload)
![Downloads](https://img.shields.io/pypi/dm/quickdownload)

A high-performance parallel file downloader that supports both HTTP/HTTPS downloads and BitTorrent downloads, with intelligent resume capabilities and robust error handling. **2-5x faster** than traditional tools like `wget` and `curl`.

## Key Features

- **Parallel Downloads**: Split HTTP files into multiple chunks and download simultaneously (up to 24 threads)
- **Smart Resume**: Intelligent chunk-level resume t**Q: Does `-p` work the same for torrents and HTTP downloads?**
A: No, they work differently. For HTTP: `-p` splits files into chunks for parallel downloading. For torrents: `-p` is ignored as libtorrent manages connections automatically with optimized algorithms.

**Q: What about torrent parallelism and speed?**
A: Torrent performance is controlled by libtorrent's built-in connection management, which is optimized for peer discovery and swarm connectivity. The tool includes 50+ built-in trackers for maximum peer discovery.

**Q: Why is my torrent slow?**
A: Torrent speed depends on peer availability and seeders. QuickDownload maximizes performance with comprehensive tracker lists, DHT, PEX, and optimized libtorrent settings.

**Q: Can I use throttling with torrents?**
A: Bandwidth throttling is not supported for torrents as libtorrent manages bandwidth internally. Use `--no-speed-boost` to reduce aggressiveness if needed.

**Q: Can I add custom trackers for private torrents?**
A: Yes! Use `--trackers` to add private tracker URLs. The built-in public trackers will still be used alongside your custom ones.s crashes, network failures, and interruptions
- **Download Queue System**: Add multiple downloads to a persistent queue and process them sequentially
- **Bandwidth Throttling**: Limit download speed per chunk with flexible units (1M, 500K, 2.5MB, etc.)
- **Enhanced BitTorrent Support**: Seamless handling of magnet links, .torrent files, and .torrent URLs with 50+ built-in trackers
- **Comprehensive Tracker Support**: Pre-configured with high-performance public trackers for optimal peer discovery
- **Real-time Progress**: Individual progress bars for each chunk with live speed monitoring
- **Robust Error Handling**: Advanced retry logic with exponential backoff and connection recovery
- **High Performance**: Typically 2-5x faster than `wget`/`curl` for large files
- **Chunk Verification**: Automatic corruption detection and re-download of damaged chunks
- **Configurable**: Customizable parallelism, output locations, seeding options, and custom trackers
- **Cross-Platform**: Works on Windows, macOS, and Linux with libtorrent 2.x support
- **Easy Installation**: Available on PyPI with simple `pip install`

## Performance Comparison

| Scenario | wget/curl | QuickDownload | Improvement |
|----------|-----------|---------------|-------------|
| 1GB file, good connection | ~12 minutes | ~4 minutes | **3x faster** |
| Resume at 90% completion | ~30 seconds | ~5 seconds | **6x faster** |
| Unreliable network | Often restarts from 0% | Seamless resume | **Saves hours** |

## Quick Start

### Installation

**From PyPI (Recommended):**
```bash
pip install quickdownload
```

**From Source:**
```bash
git clone https://github.com/Nikhil-K-Singh/quickdownload.git
cd quickdownload
pip install -e .
```

**For BitTorrent support**, install libtorrent:
```bash
# macOS with Homebrew
brew install libtorrent-rasterbar

# Ubuntu/Debian
sudo apt-get install python3-libtorrent

# Windows - try pip first, fallback to conda if needed
pip install libtorrent==2.0.11
# If pip fails, use conda (handles C++ dependencies automatically):
# conda install -c conda-forge libtorrent-python
```

### Basic Usage

**HTTP/HTTPS Downloads:**
```bash
# Simple download
quickdownload https://example.com/file.zip

# High-speed parallel download
quickdownload -p 16 https://example.com/largefile.zip

# Bandwidth-limited download
quickdownload --throttle 1M https://example.com/file.zip

# Custom output location
quickdownload -o ~/Downloads/file.zip https://example.com/file.zip
```

**Download Queue:**
```bash
# Add downloads to queue
quickdownload queue add https://example.com/file1.zip
quickdownload queue add https://example.com/file2.zip -p 8 --throttle 500K

# Process queue
quickdownload queue start

# Manage queue
quickdownload queue list
quickdownload queue remove job_123456
```

**BitTorrent Downloads:**
```bash
# Magnet link with comprehensive tracker support (50+ trackers)
quickdownload  "magnet:?xt=urn:btih:..."

# .torrent file
quickdownload  ubuntu.torrent

# .torrent URL
quickdownload  https://example.com/file.torrent

# With custom additional trackers
quickdownload  "magnet:?xt=urn:btih:..." --trackers "udp://custom.tracker.com:1337/announce"

# With seeding (contribute back to network for 30 minutes)
quickdownload  --seed-time 30 ubuntu.torrent

# Custom output directory
quickdownload  -o ~/Downloads "magnet:?xt=urn:btih:..."
```

# With seeding (contribute back to the network for 30 minutes)
quickdownload --seed-time 30 ubuntu.torrent
```

## Enhanced BitTorrent Features

QuickDownload includes comprehensive BitTorrent support with significant improvements:

### Built-in Tracker Support
- **50+ High-Performance Trackers**: Pre-configured with reliable public trackers
- **Automatic Peer Discovery**: Enhanced DHT, PEX, and tracker integration
- **Custom Tracker Support**: Add your own trackers for private torrents
- **Optimized for Speed**: Fast metadata retrieval and peer connections

### Tracker Configuration
```bash
# Uses 50+ built-in trackers automatically
quickdownload  "magnet:?xt=urn:btih:..."

# Add custom trackers for private torrents
quickdownload  "magnet:?xt=urn:btih:..." --trackers \
  "udp://private.tracker.com:1337/announce" \
  "http://another.tracker.com/announce"

# Multiple custom trackers
quickdownload ubuntu.torrent --trackers \
  "udp://tracker1.example.com:6969/announce" \
  "udp://tracker2.example.com:1337/announce"
```

### libtorrent 2.x Compatibility
- **Modern libtorrent**: Full support for libtorrent 2.0.11+
- **Optimized Settings**: Tuned for maximum download performance
- **Better Error Handling**: Improved connectivity and resume capabilities
- **Cross-Platform**: Consistent behavior across Windows, macOS, and Linux

## Why QuickDownload?

Traditional download tools like `wget` and `curl` were designed decades ago. QuickDownload brings modern capabilities:

- **Multi-connection downloading** utilizes full bandwidth
- **Intelligent resume** never loses progress, even with parameter changes
- **Download queue system** manages multiple files efficiently
- **Bandwidth throttling** provides precise speed control for shared networks
- **Unified interface** for HTTP and BitTorrent protocols  
- **Professional progress display** without clutter
- **Enterprise-grade error handling** for production use

## Command Reference

### Command Line Options

| Option | Short | Description | Default | Applies To |
|--------|-------|-------------|---------|------------|
| `--output` | `-o` | Custom output filename/directory | Current directory | Both |
| `--parallel` | `-p` | Number of parallel connections (HTTP only, ignored for torrents) | 4 | HTTP only |
| `--throttle` | | Bandwidth limit per chunk (HTTP only) | No limit | HTTP only |
| `--seed-time` | | Time to seed after torrent download (minutes) | 0 | Torrent only |
| `--trackers` | | Additional tracker URLs for torrents | Built-in 50+ trackers | Torrent only |
| `--no-speed-boost` | | Disable torrent speed optimizations | Speed boost enabled | Torrent only |
| `--help` | `-h` | Show help message | - | Both |

### Queue Management Commands

| Command | Description | Example |
|---------|-------------|---------|
| `queue add` | Add download to queue | `quickdownload queue add <url> -p 8 --throttle 1M` |
| `queue start` | Process queue sequentially | `quickdownload queue start` |
| `queue list` | Show all queued downloads | `quickdownload queue list` |
| `queue status` | Show queue statistics | `quickdownload queue status` |
| `queue remove` | Remove specific job | `quickdownload queue remove job_123` |
| `queue clear` | Clear completed jobs | `quickdownload queue clear` |
| `queue stop` | Stop queue processing | `quickdownload queue stop` |

### Progress Display

QuickDownload shows clean, professional progress output:

```
Chunk  0: DOWN [██████████░░░░░░░░░░]  50.1%   20.9 MB/41.7 MB  
Chunk  1: DONE [████████████████████] 100.0%   41.0 MB/41.0 MB  
Chunk  2: DOWN [████████░░░░░░░░░░░░]  40.2%   16.8 MB/41.8 MB  
──────────────────────────────────────────────────────────────────
Overall: [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 32.1% (658.2 MB/2.0 GB)
```

## Advanced Usage

### HTTP Download Examples

**Maximum Performance:**
```bash
# Use 16 parallel connections for maximum speed
quickdownload -p 16 https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso
```

**Custom Output:**
```bash
# Download to specific location with custom name
quickdownload -o ~/Downloads/ubuntu.iso https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso
```

**Conservative Bandwidth:**
```bash
# Use fewer connections for shared networks
quickdownload -p 2 https://example.com/file.zip
```

### BitTorrent Examples

**Linux Distributions:**
```bash
# Download Ubuntu (magnet link with 50+ built-in trackers)
quickdownload download "magnet:?xt=urn:btih:..."

# Download from .torrent file
quickdownload download ~/Downloads/ubuntu-22.04-desktop-amd64.iso.torrent

# Download from .torrent URL  
quickdownload download https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso.torrent
```

**Advanced Torrent Options:**
```bash
# Custom output directory with seeding
quickdownload  -o ~/Downloads --seed-time 30 "magnet:?xt=urn:btih:..."

# Private tracker with custom trackers
quickdownload  "magnet:?xt=urn:btih:..." --trackers \
  "udp://private.tracker.org:1337/announce" \
  "http://backup.tracker.org/announce"

# Disable speed optimizations for slow connections
quickdownload  --no-speed-boost "magnet:?xt=urn:btih:..."

# Combined options
quickdownload  -o ~/Torrents --seed-time 60 --trackers \
  "udp://extra.tracker.com:6969/announce" "magnet:?xt=urn:btih:..."
```

**Note on Torrent Parallelism:**
For torrent downloads, the `-p` flag is ignored as libtorrent manages connections automatically using optimized algorithms. Torrent performance is controlled by built-in libtorrent settings that are tuned for maximum speed and peer connectivity.

## Queue System

QuickDownload includes a powerful queue system for managing multiple downloads:

### Adding Downloads to Queue

```bash
# Basic queue addition
quickdownload queue add https://example.com/file1.zip

# With custom settings
quickdownload queue add https://example.com/file2.zip -p 8 -o ~/Downloads/

# With bandwidth throttling
quickdownload queue add https://example.com/file3.zip --throttle 1M

# Multiple files with different settings
quickdownload queue add https://example.com/large_file.zip -p 16 --throttle 2M
quickdownload queue add https://example.com/small_file.zip -p 4 --throttle 500K
```

### Processing Queue

```bash
# Start processing all pending downloads
quickdownload queue start

# View queue status
quickdownload queue list
```

**Example Queue Output:**
```
Download Queue (3 jobs):
================================================================================
COMPLETED job_1754503665_0
   URL: https://example.com/file1.zip
   Output: file1.zip
   Parallel: 4
   Throttle: 1M per chunk
   Status: completed
   Progress: 100.0%

DOWNLOADING job_1754503666_1
   URL: https://example.com/file2.zip
   Output: ~/Downloads/file2.zip
   Parallel: 8
   Status: downloading
   Progress: 45.2%

PENDING job_1754503667_2
   URL: https://example.com/file3.zip
   Parallel: 4
   Throttle: 500K per chunk
   Status: pending
```

### Queue Management

```bash
# View queue status
quickdownload queue status

# Remove specific job
quickdownload queue remove job_1754503667_2

# Clear completed downloads
quickdownload queue clear

# Stop queue processing
quickdownload queue stop
```

**Queue Features:**
- **Persistent Storage**: Queue survives system restarts
- **Sequential Processing**: Downloads one file at a time to avoid conflicts
- **Individual Settings**: Each job can have different parallelism and throttling
- **Resume Support**: Queue jobs support the same smart resume features
- **Error Handling**: Failed jobs can be retried automatically
- **Progress Tracking**: Real-time status for all queued downloads

## Bandwidth Throttling

Control download speed with flexible bandwidth limiting:

### Throttling Syntax

```bash
# Throttle examples
quickdownload --throttle 1M https://example.com/file.zip     # 1 Megabyte per second
quickdownload --throttle 500K https://example.com/file.zip   # 500 Kilobytes per second
quickdownload --throttle 2.5MB https://example.com/file.zip  # 2.5 Megabytes per second
quickdownload --throttle 100k https://example.com/file.zip   # 100 Kilobytes per second (lowercase)
```

**Supported Units:**
- `M` or `m`: Megabytes per second (e.g., `1M` = 1,000,000 bytes/sec)
- `K` or `k`: Kilobytes per second (e.g., `500K` = 500,000 bytes/sec)
- `MB`: Megabytes per second (e.g., `1MB` = 1,000,000 bytes/sec)
- `KB`: Kilobytes per second (e.g., `100KB` = 100,000 bytes/sec)
- No unit: Bytes per second (e.g., `1000` = 1,000 bytes/sec)
- Decimal values supported: `1.5M`, `2.5K`, etc.

### Throttling with Parallel Downloads

```bash
# Each of 8 chunks limited to 200K (total ~1.6M)
quickdownload -p 8 --throttle 200K https://example.com/file.zip

# Conservative bandwidth usage
quickdownload -p 4 --throttle 100K https://example.com/file.zip
```

### Use Cases for Throttling

**Shared Networks:**
```bash
# Be considerate on shared connections
quickdownload --throttle 500K https://example.com/file.zip
```

**Background Downloads:**
```bash
# Limit impact on other applications
quickdownload --throttle 200K -p 2 https://example.com/large_file.zip
```

**Metered Connections:**
```bash
# Control data usage carefully
quickdownload --throttle 100K https://example.com/file.zip
```

**Queue with Mixed Speeds:**
```bash
# Priority downloads with higher speeds
quickdownload queue add https://urgent.com/file.zip --throttle 2M -p 8
quickdownload queue add https://background.com/file.zip --throttle 200K -p 2
```

**Throttling Features:**
- **Per-Chunk Limiting**: Each parallel chunk respects the speed limit
- **Smooth Rate Control**: Token bucket algorithm prevents speed bursts
- **Flexible Units**: Supports bits, bytes, and decimal multipliers
- **Queue Compatible**: Works seamlessly with the queue system
- **Real-time Display**: Shows current throttle limits in progress output

### Smart Resume System

QuickDownload's resume system is intelligent and robust:

```bash
# Start a large download
quickdownload -p 8 -o large_file.zip https://example.com/large_file.zip

# ... download interrupted (Ctrl+C, network failure, crash) ...

# Resume with same command - automatically detects and continues
quickdownload -p 8 -o large_file.zip https://example.com/large_file.zip
# Output: "Found existing download progress - checking chunks..."
# Output: "Resuming previous download..."
```

**Resume Features:**
- Survives computer crashes and restarts
- Handles network failures gracefully  
- Verifies chunk integrity before resuming
- Re-downloads corrupted chunks automatically
- Works with any interruption (Ctrl+C, system shutdown, etc.)

## How It Works

### Technical Architecture

1. **File Analysis**: Determines file size and server range request support
2. **Smart Chunking**: Divides file into optimal chunks based on parallelism
3. **Parallel Execution**: Downloads chunks simultaneously using ThreadPoolExecutor
4. **Progress Persistence**: Continuously saves state in JSON progress files
5. **Chunk Verification**: Validates each chunk before marking as complete
6. **Error Recovery**: Implements exponential backoff for failed chunks
7. **Assembly**: Combines verified chunks into final file
8. **Cleanup**: Removes temporary files on successful completion

### Error Handling

QuickDownload implements enterprise-grade error handling:

- **Connection Errors**: Exponential backoff retry (1s, 2.5s, 5s, 9.5s, 16s)
- **Partial Failures**: Failed chunks don't affect successful ones
- **Corruption Detection**: Automatic chunk size verification and re-download
- **Network Recovery**: Intelligent reconnection on network restoration
- **Graceful Fallback**: Single-threaded mode for unsupported servers

## Performance & Benchmarks

### Real-World Performance

**Large File Downloads (1GB Ubuntu ISO):**
```bash
# Traditional wget
wget https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso
# Time: ~12 minutes (100Mbps connection)
# Resume: Basic, loses progress on corruption

# QuickDownload  
quickdownload -p 8 https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso
# Time: ~4 minutes (same connection) - 3x faster!
# Resume: Intelligent, chunk-level verification
```
## Advanced: Distributed Cluster Downloading with Registration

QuickDownload's most advanced feature: distribute downloads across multiple devices on your network with **explicit node registration** for maximum control and reliability.

**Setup Multi-Device Cluster**

**Initialize each device (run once per device):**
```bash
# Device 1 (Main laptop)
quickdownload cluster init
quickdownload cluster set "main-laptop"

# Device 2 (Gaming desktop)  
quickdownload cluster init
quickdownload cluster set "gaming-desktop"

# Device 3 (Home server)
quickdownload cluster init
quickdownload cluster set "home-server"
```

**Registration-Based Downloads**

**Step 1: Coordinator starts download session**
```bash
quickdownload cluster download --required-nodes 3 --wait-time 60 \
  -p 30 "https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso"

# Output shows session ID: abc123def456
```

**Step 2: Other nodes choose to participate**
```bash
# On each device that wants to help:
quickdownload cluster register abc123def456

# Or check status first:
quickdownload cluster status
```

**Step 3: Download starts automatically**
Once enough nodes register, download begins with intelligent chunk distribution and local sharing.

**Session Management**

**Check cluster and registration status:**
```bash
quickdownload cluster status
# Shows all nodes and your active registrations
```

**Withdraw from downloads:**
```bash
# Leave specific download
quickdownload cluster unregister abc123def456

# Leave all active downloads
quickdownload cluster withdraw
```

**Advanced Registration Options**

**Flexible node requirements:**
```bash
# Require minimum 2 nodes, wait up to 45 seconds
quickdownload cluster download --required-nodes 2 --wait-time 45 \
  -p 20 "https://example.com/large-file.zip"

# Start immediately with any available nodes
quickdownload cluster download --required-nodes 1 --wait-time 5 \
  "https://example.com/urgent-file.zip"
```

**Bandwidth-controlled cluster downloads:**
```bash
# Each node's chunks limited to 1MB/s
quickdownload cluster download --throttle 1M --required-nodes 4 \
  -p 24 "https://example.com/massive-file.zip"
```

**Key Registration Benefits**

- **Voluntary participation** - nodes choose which downloads to join
- **Graceful withdrawal** - leave downloads without disrupting others  
- **Resource control** - manage device load explicitly
- **Session isolation** - multiple downloads with different node sets
- **Predictable performance** - coordinator knows exact participating nodes



### Feature Comparison

| Feature | wget | curl | QuickDownload |
|---------|------|------|---------------|
| HTTP parallel chunks | No | No | Yes (1-24 threads) |
| Torrent piece parallelism | No | No | Yes (1-24 pieces) |
| Smart resume | No | No | Yes (Chunk-level) |
| Download queue | No | No | Yes (Persistent queue) |
| Bandwidth throttling | No | No | Yes (Per-chunk/piece limiting) |
| Corruption detection | No | No | Yes (Automatic) |
| BitTorrent support | No | No | Yes (Full support) |
| Multi-device cluster | No | No | Yes (Registration-based) |
| Progress bars | Basic | Basic | **Multi-chunk/piece** |
| Error recovery | Basic | Basic | **Advanced** |
| Speed (large files) | 1x | 1x | **2-5x faster** |

### Performance Tips

**Optimal Thread Count for HTTP:**
- **Fast connections (100+ Mbps)**: 8-16 threads
- **Standard connections (25-100 Mbps)**: 4-8 threads  
- **Slow connections (<25 Mbps)**: 2-4 threads
- **Shared networks**: 2-4 threads to be considerate

**Optimal Thread Count for Torrents:**
- **Popular torrents (many seeders)**: 8-16 pieces
- **Standard torrents**: 4-8 pieces
- **Rare torrents (few seeders)**: 2-4 pieces
- **Private trackers**: Follow community guidelines (usually 4-8)

**When to Use QuickDownload:**
- Files larger than 100MB
- Unreliable networks where resume is critical
- High-speed connections that can benefit from parallelism
- When you need BitTorrent + HTTP in one tool
- Multi-device scenarios with cluster downloading

## Technical Details

### Resume Implementation

QuickDownload implements sophisticated resume functionality:

**Progress Tracking:**
- Creates `.progress` files containing download metadata
- Tracks completed chunks, file size, and parameters
- Validates chunk integrity on resume attempts
- Automatically handles parameter changes gracefully

**State Management:**
- Temporary `.part{N}` files for each chunk during download
- JSON progress files for persistent state tracking  
- Automatic cleanup on successful completion
- Corruption detection and automatic re-download

**Chunk Verification:**
- File size validation for each chunk
- Automatic re-download of corrupted/missing chunks
- Smart recovery that only downloads what's needed
- Integrity checking before final assembly

### Supported Protocols & Servers

**HTTP/HTTPS Support:**
- Servers with HTTP Range Request support (HTTP 206 Partial Content)
- Automatic detection of server capabilities
- Graceful fallback to single-threaded for unsupported servers
- Custom headers and authentication (when supported by server)

**BitTorrent Support:**
- Magnet links with full DHT support
- .torrent files (local and remote URLs)
- Tracker and peer discovery
- Optional seeding with configurable time limits

### Parallelism: HTTP vs BitTorrent

**HTTP Downloads (`-p` flag):**
- Splits **single file** into chunks based on byte ranges
- Downloads **different byte ranges** simultaneously from same server
- Higher parallelism = more simultaneous chunk downloads
- Limited by server's range request support and connection limits

**BitTorrent Downloads (`-p` flag):**
- Requests **different pieces** simultaneously from multiple peers
- Each piece is a complete data unit (typically 256KB-4MB)
- Higher parallelism = more simultaneous piece requests across peer swarm
- Limited by peer availability and network etiquette

**Optimal Settings Guide:**

| Connection Speed | HTTP `-p` | Torrent `-p` | Notes |
|-----------------|-----------|--------------|-------|
| < 25 Mbps | 2-4 | 2-4 | Conservative for shared networks |
| 25-100 Mbps | 4-8 | 4-8 | Standard broadband performance |
| 100+ Mbps | 8-16 | 8-16 | High-speed connections |
| Gigabit+ | 16-24 | 12-20 | Maximum performance |

**Performance Considerations:**
- **Popular torrents**: Can handle higher parallelism (many seeders available)
- **Rare torrents**: Use lower parallelism (few peers, be courteous)
- **Private trackers**: Follow community guidelines for connection limits
- **System resources**: Each parallel stream uses memory and CPU

### System Requirements

- **Python**: 3.7 or higher
- **Dependencies**: requests, libtorrent-python (for torrent support)
- **Disk Space**: Sufficient space for target file + temporary chunks
- **Network**: Any connection speed (optimizes automatically)
- **Platform**: Windows, macOS, Linux

## FAQ

**Q: How many parallel downloads should I use?**
A: Start with 4-8 threads. Optimal number depends on your connection speed and server capacity. More isn't always better due to overhead.

**Q: Does this work with all websites?**
A: QuickDownload works with any server supporting HTTP range requests. For servers without range support, it falls back to single-threaded download (still works, just no parallelism).

**Q: Can I resume interrupted downloads?**
A: Yes! QuickDownload automatically saves progress and resumes exactly where it left off. Simply run the same command again.

**Q: What if my computer crashes during download?**
A: No problem! Progress is saved continuously. On restart, QuickDownload verifies existing chunks and downloads only what's missing or corrupted.

**Q: How does chunk verification work?**
A: Each chunk is verified for size and integrity before being marked complete. Corrupted chunks are automatically re-downloaded.

**Q: What temporary files are created?**
A: During download: `filename.part0`, `filename.part1`, etc. (chunk files) and `filename.progress` (progress file). All are cleaned up automatically on completion.

**Q: Can I change parallelism for resumed downloads?**
A: Currently, you must use the same parameters (URL, output filename, parallel count) to resume. Changing parameters starts fresh.

**Q: How much faster is parallel downloading?**
A: Typically 2-5x faster than single-threaded downloads, depending on your connection and server capabilities.

**Q: Is QuickDownload safe to use?**
A: Yes, QuickDownload only downloads files and doesn't execute code. However, always be cautious about what you download from the internet.

**Q: How does the queue system work?**
A: The queue stores jobs in `~/.quickdownload/queue.json` and processes them sequentially. Each job can have different settings (parallelism, throttling, output location). The queue persists across system restarts.

**Q: How does bandwidth throttling work?**
A: Throttling uses a token bucket algorithm to limit each chunk's download speed. With `-p 4 --throttle 1M`, each of the 4 chunks is limited to 1 Mbps, giving roughly 4 Mbps total speed.

**Q: Does `-p` work the same for torrents and HTTP downloads?**
A: No, they work differently. For HTTP: `-p` splits one file into chunks from the same server. For torrents: `-p` controls how many pieces are requested simultaneously from different peers in the swarm.

**Q: What `-p` value should I use for torrents?**
A: Start with 4-8 for most torrents. Use higher values (8-16) for popular torrents with many seeders, and lower values (2-4) for rare torrents or slow connections.

**Q: Why is my torrent slow even with high `-p` value?**
A: Torrent speed depends on peer availability, not just parallelism. A rare torrent with few seeders won't benefit from high `-p` values. Also, some peers may have upload limits.

**Q: Can I use throttling with torrents?**
A: Yes! Use `--throttle` with torrents to limit bandwidth usage. This is especially helpful on shared networks or when downloading in the background.

**Q: Can I throttle the total download speed instead of per-chunk?**
A: Currently, throttling is per-chunk. For total speed control, calculate: `desired_total_speed ÷ parallel_chunks = per_chunk_limit`. For example, for 2 Mbps total with 4 chunks: `--throttle 500K -p 4`.

**Q: Can I add downloads to the queue while it's processing?**
A: Yes! You can add new jobs with `quickdownload queue add` while the queue is running. New jobs will be processed after current ones complete.

**Q: Why choose QuickDownload over wget/curl?**
A: QuickDownload offers parallel downloading, intelligent resume, download queue, bandwidth throttling, enhanced BitTorrent support with 50+ trackers, and better progress visualization - all in a modern, robust tool.

## Changelog

### Latest Updates (August 23, 2025)

#### Enhanced BitTorrent Support
- **ibtorrent 2.0.11 Compatibility**: Full support for modern libtorrent with optimized settings
- **50+ Built-in Trackers**: Comprehensive list of high-performance public trackers for maximum peer discovery
- **Faster Metadata Retrieval**: Improved magnet link handling with enhanced tracker integration
- **Custom Tracker Support**: Add private tracker URLs with `--trackers` option
- **Optimized Settings**: Tuned libtorrent configuration for maximum download performance
- **Better Error Handling**: Improved connectivity and compatibility across platforms

#### Command Line Improvements
- **Clarified `-p` Flag Behavior**: HTTP downloads use parallel chunks, torrents use optimized libtorrent connection management
- **Torrent-Specific Options**: Added `--trackers` and `--no-speed-boost` flags for torrents
- **Updated Documentation**: Comprehensive examples and usage patterns for both HTTP and torrent downloads

#### Technical Enhancements
- **Enhanced Magnet URI Processing**: Automatic tracker injection for better peer connectivity
- **Session Optimization**: Improved DHT, PEX, and peer discovery settings
- **Cross-Platform Stability**: Consistent behavior across Windows, macOS, and Linux

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Download stuck at "Analyzing file..." | Server may be slow to respond. Check internet connection and try again. |
| "Range requests supported: False" | Server doesn't support parallel downloads. Will use single-threaded mode (still works). |
| Resume not working | Ensure same command parameters (URL, output file, parallel count) as original download. |
| Chunks failing repeatedly | Try reducing parallel count: `quickdownload -p 2 <url>` |
| BitTorrent not working | Install libtorrent: `pip install libtorrent` or use system package manager. |
| Permission errors | Check write permissions for output directory. |
| Queue not saving jobs | Check write permissions for `~/.quickdownload/` directory. |
| Throttling not working | Verify throttle syntax (e.g., `1M`, `500K`). Check that server supports range requests for parallel chunks. |
| Queue processing stops | Use `quickdownload queue status` to check for failed jobs. Restart with `quickdownload queue start`. |

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/Nikhil-K-Singh/quickdownload.git
cd quickdownload

# Install in development mode
pip install -e .

```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with Python's `concurrent.futures` for parallel processing
- Uses `libtorrent` for BitTorrent protocol support
- Inspired by the need for faster, more reliable downloads in the modern era

---

**Made with care for faster, more reliable downloads**

[![GitHub](https://img.shields.io/badge/GitHub-Nikhil--K--Singh-blue?logo=github)](https://github.com/Nikhil-K-Singh)
[![PyPI](https://img.shields.io/badge/PyPI-quickdownload-blue?logo=pypi)](https://pypi.org/project/quickdownload/)
