aiosu

Simple and fast asynchronous osu! API v1 and v2 library with various utilities.

Features

Support for modern async syntax (async with)
Support for API v1 and API v2
Rate limit handling
Utilities for osu! related calculations
Easy to use

Installing

Python 3.12 or higher is required

To install the library, simply run the following commands

# Linux/macOS
python3 -m pip install -U aiosu

# Windows
py -3 -m pip install -U aiosu

To install the development version, do the following:

$ git clone https://github.com/NiceAesth/aiosu
$ cd aiosu
$ python3 -m pip install -U .

API v1 Example

import aiosu
import asyncio


async def main():
    # async with syntax
    async with aiosu.v1.Client("osu api token") as client:
        user = await client.get_user(7782553)

    # regular syntax
    client = aiosu.v1.Client("osu api token")
    user = await client.get_user(7782553)
    await client.aclose()


if __name__ == "__main__":
    asyncio.run(main())

API v2 Example

import aiosu
import asyncio
import datetime


async def main():
    token = aiosu.models.OAuthToken.model_validate(json_token_from_api)

    # or

    token = aiosu.models.OAuthToken(
        access_token="access token",
        refresh_token="refresh token",
        expires_on=datetime.datetime.now(datetime.UTC)
        + datetime.timedelta(days=1),  # can also be string
    )

    # async with syntax
    async with aiosu.v2.Client(
        client_secret="secret", client_id=1000, token=token
    ) as client:
        user = await client.get_me()

    # regular syntax
    client = aiosu.v2.Client(client_secret="secret", client_id=1000, token=token)
    user = await client.get_me()
    await client.aclose()


if __name__ == "__main__":
    asyncio.run(main())

You can find more examples in the examples directory.

Contributing

Please read the CONTRIBUTING.rst to learn how to contribute to aiosu!

Acknowledgments

discord.py for README formatting
osu!Akatsuki for performance and accuracy utils

Metadata

Release files for aiosu 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiosu 3.0.0
File	Size	Uploaded
aiosu-3.0.0.tar.gz	75.0 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aiosu 3.0.0
File	Interpreter	ABI	Platform	Reset
aiosu-3.0.0-py3-none-any.whl 97.3 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 172.3 kB

Release files / aiosu-3.0.0.tar.gz

Download URL	aiosu-3.0.0.tar.gz
Size	75.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`4be58c3d3488539c80a7f2c35bd9b9ea83df37370b0c55d96113b16c0a396e7e`
BLAKE2b-256 checksum How to use checksums	`9b62f39bae9c6af98fbc5d26ac071f3672ddd15b7b894fc0fcd02a3b9c188cb8`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.1 CPython/3.12.14 Linux/6.17.0-1022-azure`

Release files / aiosu-3.0.0-py3-none-any.whl

Download URL	aiosu-3.0.0-py3-none-any.whl
Size	97.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c946d26bf92d77e6d67baeaf75ffe1ec9046c6a18743fabfc15b6e486482c61a`
BLAKE2b-256 checksum How to use checksums	`95d9614c0bd49d8a8a143343987d1e336f93164733d6ad86b572c38afa5740db`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.1 CPython/3.12.14 Linux/6.17.0-1022-azure`