Python wrapper for the Mastodon ( https://github.com/mastodon/mastodon/ ) API. Feature complete for public API as of Mastodon version 4.5.8 and easy to get started with:
from mastodon import Mastodon
# Register your app! This only needs to be done once (per server, or when
# distributing rather than hosting an application, most likely per device and server).
# Uncomment the code and substitute in your information:
'''
Mastodon.create_app(
'pytooterapp',
api_base_url = 'https://mastodon.social',
to_file = 'pytooter_clientcred.secret'
)
'''
# Then, log in. This can be done every time your application starts, or you can use the persisted information:
mastodon = Mastodon(client_id = 'pytooter_clientcred.secret',)
print(mastodon.auth_request_url())
# open the URL in the browser and paste the code you get
mastodon.log_in(
code=input("Enter the OAuth authorization code: "),
to_file="pytooter_usercred.secret"
)
# To post, create an actual API instance:
mastodon = Mastodon(access_token = 'pytooter_usercred.secret')
mastodon.toot('Tooting from Python using #mastodonpy !')You can install Mastodon.py via pypi:
pip install Mastodon.pyWe currently try to support Python 3.7 and above, and try to at least not break Python 3 versions below that. Python 2 support is no longer a goal.
Full documentation and basic usage examples can be found at https://mastodonpy.readthedocs.io/en/stable/ . Some more extensive examples can be found at https://github.com/halcy/MastodonpyExamples
If you have any questions about using the library or think you have found a bug, please feel free to open an issue, a github discussion thread, or to just directly contact @halcy@icosahedron.website on the Fediverse or .halcy on Discord - we’ll try to respond as quickly as possible.
Citing
If you use Mastodon.py as part of your research, please review and cite the following paper:
Diener et al., (2026). Mastodon.py: A Python library for the Mastodon API. Journal of Open Source Software, 11(120), 8946, https://doi.org/10.21105/joss.08946
Acknowledgements
Mastodon.py contains work by a large amount of contributors, many of which have put significant work into making it a better library. You can find some information about who helped with which particular feature or fix in the changelog.
1 maintainer
Metadata
1 maintainer
Release files for Mastodon.py 2.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mastodon_py-2.2.2.tar.gz | 11.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mastodon_py-2.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 11.9 MB
Release files / mastodon_py-2.2.2.tar.gz
| Download URL | mastodon_py-2.2.2.tar.gz |
|---|---|
| Size | 11.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
07131f6ac8820462de25b7641622b01b22f2b9ab6b3e7252749442f51fd30778
|
|
BLAKE2b-256 checksum How to use checksums |
cfbf91465842e820ac8c2c90fda9c7875ed40d3abb934e072d76cbdb4462027b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency logRelease files / mastodon_py-2.2.2-py3-none-any.whl
| Download URL | mastodon_py-2.2.2-py3-none-any.whl |
|---|---|
| Size | 131.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d18a107517836c783c93c9f2e713b4fad909fcd017f5036d2ce93d3dfd781904
|
|
BLAKE2b-256 checksum How to use checksums |
2fce970923430cf0986470964445ccfde77f79a53dec34bd89927ccec49d1c63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency log
