Build Status

This is a Python library for interfacing with Marathon servers via Marathon's REST API.


  • For Marathon 1.4.0, use at least 0.8.7
  • For Marathon 1.1.1 and 0.15.x, use at least 0.8.1
  • For Marathon 0.14.x, use at least 0.7.6
  • For Marathon 0.8.x-0.11.x, use at least marathon-python 0.7.5
  • For Marathon 0.8.x-0.9.x, use as least marathon-python 0.6.11 - 0.7.4
  • For Marathon 0.7.x, use at least marathon-python 0.6.10
  • For all version changes, please see

If you find a feature that is broken, please submit a PR that adds a test for it so it will be fixed and will continue to stay fixed as Marathon changes over time.

Just because this library is tested against a specific version of Marathon, doesn't necessarily mean that it supports every feature and API Marathon provides.


From PyPi (recommended)

pip install marathon

From GitHub

pip install -e

From source

git clone
python marathon-python/ install


marathon-python uses Travis to test the code against different versions of Marathon. You can run the tests locally on a Linux machine that has docker on it:

Running The Tests

make itests

Running The Tests Against a Specific Version of Marathon

MARATHONVERSION=0.9.0 make itests


API documentation is here.

Or you can build the documentation yourself:

pip install sphinx
pip install sphinx_rtd_theme
cd docs/
make html

The documentation will be in <project-root>/gh-pages/html:

open gh-pages/html/index.html

Basic Usage

Create a MarathonClient() instance pointing at your Marathon server(s):

>>> from marathon import MarathonClient
>>> c = MarathonClient('http://localhost:8080')

>>> # or multiple servers:
>>> c = MarathonClient(['http://host1:8080', 'http://host2:8080'])

Then try calling some methods:

>>> c.list_apps()
[MarathonApp::myapp1, MarathonApp::myapp2]
>>> from marathon.models import MarathonApp
>>> c.create_app('myapp3', MarathonApp(cmd='sleep 100', mem=16, cpus=1))
>>> app = c.get_app('myapp3')
>>> app.ports
>>> app.mem = 32
>>> c.update_app('myapp3', app)
{'deploymentId': '83b215a6-4e26-4e44-9333-5c385eda6438', 'version': '2014-08-26T07:37:50.462Z'}
>>> c.get_app('myapp3').mem
>>> c.get_app('myapp3').instances
>>> c.scale_app('myapp3', instances=3)
{'deploymentId': '611b89e3-99f2-4d8a-afe1-ec0b83fdbb88', 'version': '2014-08-26T07:40:20.121Z'}
>>> c.get_app('myapp3').instances
>>> c.scale_app('myapp3', delta=-1)
{'deploymentId': '1081a99c-55e8-4404-907b-4a3697059848', 'version': '2014-08-26T07:43:30.232Z'}
>>> c.get_app('myapp3').instances
>>> c.list_tasks('myapp1')
>>> c.kill_tasks('myapp1', scale=True)
>>> c.list_tasks('myapp1')


Open source under the MIT License. See LICENSE.