Mastodon.py is an actively maintained Python wrapper for the Mastodon API, providing a feature-complete client for interacting with Mastodon instances. It is currently at version 2.2.1 and receives regular updates to support new Mastodon API features and fix bugs.
pip install Mastodon.pyVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to authenticate with a Mastodon instance using an access token and post a status (toot). It assumes you have already registered an application and obtained a user access token. For production, store your `MASTODON_ACCESS_TOKEN` and `MASTODON_API_BASE_URL` as environment variables. The commented-out sections show the `create_app` and `log_in` steps for initial setup.
Thoroughly test your application after upgrading to v2.0.0 or later, especially if you rely on specific dict-like access patterns or type checks. Review the new entity classes and type hints in the documentation.
Always explicitly provide the `api_base_url` when calling `Mastodon.create_app()` and when initializing the `Mastodon` client instance, e.g., `api_base_url='https://example.social'`.
Ensure you are using `mastodon-py` version 2.1.3 or newer to benefit from internal handling of these deprecation warnings. Keep your `mastodon-py` library updated.
If encountering `invalid_grant` errors during login, temporarily disable 2FA or use an application-specific password if available (check your instance's settings). Ensure the email address used for login is in all lowercase.
Configure `ratelimit_method` when initializing `Mastodon`. The default is 'wait', which will pause. For immediate errors, set `ratelimit_method='throw'` and implement custom retry logic with exponential backoff. Monitor `ratelimit_remaining` and `ratelimit_reset` attributes.
Verify the `access_token` is correct and hasn't expired. If using OAuth, ensure the `redirect_uri` and `scopes` passed to `log_in()` match those used in `create_app()` and the authorization URL. If 2FA is enabled on your Mastodon account, consider generating an application-specific password or temporarily disabling 2FA for bot accounts if appropriate, or ensure your OAuth flow is correctly handling the authorization code.
Double-check the ID or URL of the resource you are trying to access. Ensure the `api_base_url` is correct for the instance. Verify that the authenticated user's scope and permissions allow access to the specific API endpoint and resource.
Always explicitly pass the `api_base_url` parameter when initializing `Mastodon` or calling `Mastodon.create_app()`. Example: `mastodon = Mastodon(api_base_url='https://example.social', ...)`.
By default, `mastodon-py` will wait. If you configured `ratelimit_method='throw'`, you need to implement your own retry logic with a delay. Check the `ratelimit_reset` attribute on the `Mastodon` object to know when to retry, or use `time.sleep()` for the duration indicated in the error message.