A wrapper around the Trello API written in Python. Each Trello object is represented by a corresponding Python object. The attributes of these objects are cached, but the child objects are not. This can possibly be improved when the API allows for notification subscriptions; this would allow caching (assuming a connection was available to invalidate the cache as appropriate).

I’ve created a Trello Board for feature requests, discussion and some development tracking.


pip install py-trello


from trello import TrelloClient

client = TrelloClient(

Where token and token_secret come from the 3-legged OAuth process and api_key and api_secret are your Trello API credentials that are (generated here).

To use without 3-legged OAuth, use only api_key and api_secret on client.

Working with boards

all_boards = client.list_boards()
last_board = all_boards[-1]

working with board lists and cards

all_boards = client.list_boards()
last_board = all_boards[-1]
my_list = last_board.get_list(list_id)

for card in my_list.list_cards():

Getting your Trello OAuth Token

Make sure the following environment variables are set:


These are obtained from the link mentioned above.

TRELLO_EXPIRATION is optional. Set it to a string such as ‘never’ or ‘1day’. Trello’s default OAuth Token expiration is 30 days.

Default permissions are read/write.

More info on setting the expiration here: https://trello.com/docs/gettingstarted/#getting-a-token-from-a-user


python -m trello oauth

Required Python modules

Found in requirements.txt


To run the tests, run python -m unittest discover. Four environment variables must be set:

  • TRELLO_API_KEY: your Trello API key
  • TRELLO_TOKEN: your Trello OAuth token
  • TRELLO_TEST_BOARD_COUNT: the number of boards in your Trello account
  • TRELLO_TEST_BOARD_NAME: name of the board to test card manipulation on. Must be unique, or the first match will be used
  • TRELLO_TEST_STAR_COUNT: the number of stars on your test Trello board

WARNING: The tests will delete all cards on the board called TRELLO_TEST_BOARD_NAME!

To run tests across various Python versions, tox is supported. Install it and simply run tox from the py-trello directory.