Skip to content
Automating a tournament bracket.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Pychallonge provides python bindings for the CHALLONGE! API.


  • python-dateutil==2.4.2


pip install -e git+


import challonge

# Tell pychallonge about your [CHALLONGE! API credentials](
challonge.set_credentials("your_challonge_username", "your_api_key")

# Retrieve a tournament by its id (or its url).
tournament =

# Tournaments, matches, and participants are all represented as normal Python dicts.
print(tournament["id"]) # 3272
print(tournament["name"]) # My Awesome Tournament
print(tournament["started-at"]) # None

# Retrieve the participants for a given tournament.
participants = challonge.participants.index(tournament["id"])
print(len(participants)) # 13

# Start the tournament and retrieve the updated information to see the effects
# of the change.
tournament =["id"])
print(tournament["started-at"]) # 2011-07-31 16:16:02-04:00

See for full API documentation.

Running the unit tests

Pychallonge comes with a set of unit tests. The tests are not comprehensive, but do utilize each method and verify basic functionality.

In order to test behavior of the python bindings, API calls must be made to CHALLONGE!, which requires a username and api key. To run the tests with your credentials, set CHALLONGE_USER and CHALLONGE_KEY appropriately in your environment.

$ git clone pychallonge
$ CHALLONGE_USER=my_user CHALLONGE_KEY=my_api_key python pychallonge/
Ran 20 tests in 82.314s


Note that several tournaments are created, published, started, and completed over the course of the unit tests. These should be cleaned up by the end, but if any of the tests fail they may not be cleaned up. As long as the basic functions work, you can clean up errant tournaments as follows.

>>> import challonge
>>> challonge.set_credentials("my_user", "my_api_key")
>>> for t in challonge.tournaments.index():
...     if t["name"].startswith("pychallonge"):
...         challonge.tournaments.destroy(t["id"])
You can’t perform that action at this time.