---
id: mastodon-py
version: "2.2.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# Mastodon.py — Python wrapper for the Mastodon API

License: permissive · Maintenance: active · Downloads: 306.6K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 306.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mastodon api python client, fediverse python library, mastodon social media automation, python mastodon posting, mastodon.py wrapper, mastodon oauth authentication, mastodon timeline api, fediverse, social-media-api, oauth

[View on SkillFed](https://skillfed.io/packages/mastodon-py) · [View on PyPI](https://pypi.org/project/mastodon-py/)