btdownloadheadless [ option ... ] URL
btdownloadheadless [ option ... ] filename
btdownloadcurses [ option ... ] URL
btdownloadcurses [ option ... ] filename
btdownloadgui [ option ... ] URL
btdownloadgui [ option ... ] filename


This manual page documents briefly the btdownloadheadless, btdownloadcurses, and btdownloadgui commands. This manual page was written for the Debian distribution because the original program does not have a manual page.

These are all programs that allow a user to download files using bittorrent, a peer to peer, scatter-gather network protocol. They all have the same options.


These programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

--responsefile filename

treat filename as a file which the server reponse was stored in. If this option is used, no filename or URL should be present on the command line.

--url url

retrieve the torrent info file from url. If this option is used, no filename or URL should be present on the command line.

-i ip | --ip ip

report ip as your IP to the tracker

--bind ip

bind to ip instead of the default

--minport portnum

set portnum as the minimum port to listen on, counts up if unavailable (default 6881)

--maxport portnum

set portnum as the maximum port to listen on (default 6889)

--saveas filename

store the downloaded file to filename, instead of querying user (gui) or using the filename stored in the torrent info file

--max_uploads num

Only allow num uploads at once (default 4)

--max_upload_rate kbytes

maximum rate to upload at in kilobytes, 0 means no limit (default 0)

--keepalive_interval secs

pause secs seconds between sending keepalives (default 120.0)

--download_slice_size bytes

query for bytes bytes per request (default 32768)

--request_backlog num

keep num requests in a single pipe at once (default 5)

--max_message_length bytes

set bytes to the maximum length prefix encoding you'll accept over the wire - larger values get the connection dropped (default 8388608)

--timeout secs

wait secs before closing sockets which nothing has been recieved on (default 300.0)

--timeout_check_interval secs

check whether connections have timed out every secs seconds (default 60.0)

--max_slice_length bytes

requests from peers larger than bytes bytes are ignored (default 131072)

--max_rate_recalculate_interval secs

connections that pause longer than secs seconds are given reduced rate (default 15.0)

--max_rate_period secs

set secs to the maximum amount of time to guess the current rate estimate represents (default 20.0)

--upload_rate_fudge secs

set the time equivalent of writing to kernel-level TCP buffer to secs (default 5.0)

--display_interval secs

update displayed information every secs seconds (default 0.1)

--rerequest_interval secs

request more peers every secs seconds (default 300)

--min_peers num

do not rerequest if we have num peers already (default 20)

--http_timeout secs

wait secs seconds before assuming a http connection has timed out (default 60)

--snub_time secs

wait secs seconds for data to come in over a connection before assuming it's semi-permanently choked (default 30.0)

--spew 1 | 0

whether to display diagnostic info to stdout. This option is not useful when using btdownloadcurses or btdownloadgui. (default 0)

--max_initiate num

stop initiating new connections when we have num peers (default 40)

--check_hashes 1 | 0

whether to check hashes on disk (defaults to 1)

--report_hash_failures 1 | 0

whether to report to the user that hash failuers occur (non-fatal, common error) (default 0)

--rarest_first_priority_cutoff num

the number of peers which need to have a piece before other partials take priority over rarest first (default 3)

RELATED TO bittorrent-downloader.bittorrent…

bttrack(1), btmakemetafile(1), btlaunchmany(1).

More information on the BitTorrent protocol used for distributing files is available at

You will also find a full description on the advantages of the protocol in the academic paper Incentives Build Robustness in BitTorrent available at


This manual page was written by Michael Janssen <[email protected]>, for the Debian GNU/Linux system (but may be used by others).