Welcome to aiosu#

aiosu is an easy-to-use asynchronous wrapper for the osu! API


  • 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

Getting started#

If you are new to this library, you should familiarize yourself with the following pages:

Getting help#

If you need assistance, you should look here:

Breaking changes#

v2.0.3: The replay model has been moved to models/files/replay.py and the Replay class has been renamed to ReplayFile.

v2.0.0: The library now uses Pydantic v2. This means that the following changes have occured:

  • The dict method has been renamed to model_dump

  • The json method has been renamed to model_dump_json

  • The parse_obj method has been renamed to model_validate

  • The parse_raw method has been renamed to model_validate_json

  • The parse_file method has been renamed to model_validate_file

  • Renamed Beatmapset.nomination_summary to Beatmapset.nominations

Note: The old methods are still available with a deprecation warning, but will be removed in Pydantic v3.


aiosu has utilities for various osu! related calculations.


Documentation for the API clients can be found below.


Documentation for aiosu types can be found below.

Library Classes#

Documentation for aiosu classes can be found below.