libtorrent python binding

Author: Arvid Norberg,


Building the libtorrent python bindings will produce a shared library (DLL) which is a python module that can be imported in a python program.

building using

There is a shipped with libtorrent that can be used on windows. On windows the will invoke bjam and assume that you have boost sources at $BOOST_PATH. The resulting executable is self-contained, it does not depend any boost or libtorrent dlls.

On other systems, the is generated by running ./configure --enable-python-binding.

To build the Python bindings do:

  1. Run:

    python build
  2. As root, run:

    python install

building using boost build

To set up your build environment, you need to add some settings to your $BOOST_BUILD_PATH/user-config.jam.

Make sure your user config contains the following line:

using python : 2.3 ;

Set the version to the version of python you have installed or want to use. If you've installed python in a non-standard location, you have to add the prefix path used when you installed python as a second option. Like this:

using python : 2.6 : /usr/bin/python2.6 : /usr/include/python2.6 : /usr/lib/python2.6 ;

The bindings require at least python version 2.2.

For more information on how to install and set up boost-build, see the building libtorrent section.

Once you have boost-build set up, you cd to the bindings/python directory and invoke bjam with the apropriate settings. For the available build variants, see libtorrent build options.

For example:

$ bjam dht-support=on link=static

On Mac OS X, this will produce the following python module:


using libtorrent in python

The python interface is nearly identical to the C++ interface. Please refer to the library reference. The main differences are:

The endpoint type is represented as a tuple of a string (as the address) and an int for the port number. E.g. ('', 6881) represents the localhost port 6881.
The time duration is represented as a number of seconds in a regular integer.

The following functions takes a reference to a container that is filled with entries by the function. The python equivalent of these functions instead returns a list of entries.

  • torrent_handle::get_peer_info
  • torrent_handle::file_progress
  • torrent_handle::get_download_queue
  • torrent_handle::piece_availability

create_torrent::add_node() takes two arguments, one string and one integer, instead of a pair. The string is the address and the integer is the port.

session::apply_settings() accepts a dictionary with keys matching the names of settings in settings_pack. When calling apply_settings, the dictionary does not need to have every settings set, keys that are not present are not updated.

To get a python dictionary of the settings, call session::get_settings.

For an example python program, see in the bindings/python directory.

A very simple example usage of the module would be something like this:

import libtorrent as lt
import time
import sys

ses = lt.session({'listen_interfaces': ''})

info = lt.torrent_info(sys.argv[1])
h = ses.add_torrent({'ti': info, 'save_path': '.'})

while (not h.is_seed()):
  s = h.status()

  print('\r%.2f%% complete (down: %.1f kB/s up: %.1f kB/s peers: %d) %s' % \
    (s.progress * 100, s.download_rate / 1000, s.upload_rate / 1000, \
    s.num_peers, s.state), end=' ')

  alerts = ses.pop_alerts()
  for a in alerts:
    if a.category() & lt.alert.category_t.error_notification:



print(, 'complete')