Mastodon.py

What it is and what it does

Mastodon.py is a Python client library that wraps the Mastodon API, enabling you to interact with Mastodon servers programmatically. It handles OAuth authentication, token management, and provides methods to read timelines, search, post toots, and manage your account. The library depends on requests for HTTP calls, python-dateutil for timestamp handling, and decorator for utility functions.

You use it by first registering your application once per server to get client credentials, then authenticating with user credentials to obtain an access token. After that, you can perform API operations like posting, fetching timelines, and managing followers. The library is feature-complete for the public API as of Mastodon version 4.5.8 and is actively maintained with recent updates.

Use it for:

• Build a bot that monitors a hashtag and reposts matching toots to another account.
• Create a backup tool that periodically exports your toots and media to local storage.
• Automate posting scheduled content to Mastodon on a timer.
• Aggregate timelines from multiple Mastodon accounts into a single feed.
• Analyze Mastodon social graphs or engagement metrics for research.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Python wrapper for the Mastodon API that lets you authenticate, read timelines, and post to Mastodon servers programmatically.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and a permissive license. Install it if you need to automate or integrate with Mastodon servers from Python. The main gotcha is the OAuth setup requirement, but that is a one-time configuration step documented in the library.

Install

mastodon-py on PyPI

pip install mastodon-py

uv add mastodon-py

poetry add mastodon-py

Installing Mastodon.py

Before you install

Low install friction with only three common runtime dependencies (requests, python-dateutil, decorator). Actively maintained with a recent release 11 days ago and 957 repository stars.

License in practice

MIT license is permissive, allowing use in commercial and private projects with minimal restrictions.

Quickstart

pip install Mastodon.py

from mastodon import Mastodon

mastodon = Mastodon(access_token='pytooter_usercred.secret')
mastodon.toot('Tooting from Python using #mastodonpy !')

Requires OAuth setup: you must first call Mastodon.create_app() to register your application and obtain credentials before you can authenticate and use the API.

Verify before relying

• Whether feature completeness for Mastodon 4.5.8 extends to all current server versions or only that specific version.
• Python 3.7 support status and whether versions below 3.7 are actively tested or merely not intentionally broken.

Package facts

Evidence: mastodon_py-2.2.2-py3-none-any.whl

Keywords: mastodon, api, microblogging

Tags

More Communications packages