osu.py

osu.py is a python library that emulates part of the online functionality of the osu! stable client.

IMPORTANT: Use this library at your own risk! I am not responsible for any unexpected behavior of the client or anything that can happen to your account. If you want to test it out on a custom server, you can set the server attribute when initializing the client.

You can install this package with pip:

pip install osu

Or build it manually:

git clone https://github.com/Lekuruu/osu.py.git
cd osu.py
pip install -e .

You can also build a source distribution and wheel locally:

pip install build
python -m build

Features

Receiving player stats
Sending/Receiving chat messages
Spectating
Avatars
Comments
Replays
Scores/Leaderboards
Tournament client behaviour
Direct Search
Direct Download
Multiplayer
Documentation

Example

Here is a small example of how to use this package:

from osu.bancho.constants import ServerPackets
from osu.objects import Player
from osu import Game
import logging

# Enable extended logging
logging.basicConfig(
    level=logging.INFO,
    format='[%(asctime)s] - <%(name)s> %(levelname)s: %(message)s'
)

# Initialize the game class
game = Game(
    USERNAME,
    PASSWORD
)

# Simple message handler
@game.events.register(ServerPackets.SEND_MESSAGE)
def on_message(sender: Player, message: str, target: Player):
    if message.startswith('?ping'):
        sender.send_message('pong!')

# Run the game
game.run()

You can also run tasks, independent of server actions:

# Example of a task, running every minute
@game.tasks.register(minutes=1, loop=True)
def example_task():
    ...

For a more in-depth example, please view this project.

Metadata

Release files for osu 1.5.4

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

Source distribution (sdist)

Source distribution for osu 1.5.4
File	Size	Uploaded
osu-1.5.4.tar.gz	39.2 kB	Jul 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for osu 1.5.4
File	Interpreter	ABI	Platform	Reset
osu-1.5.4-py3-none-any.whl 47.4 kB Jul 9, 2026	Python 3	none	any	Details

Total release size: 86.5 kB

Release files / osu-1.5.4.tar.gz

Download URL	osu-1.5.4.tar.gz
Size	39.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`81e15316dedff6950222b9d489e3592631f282b392baedef08923e0628d3143f`
BLAKE2b-256 checksum How to use checksums	`6330588898f43d59a681e6c0bbb30c0339f9f4bfb4d1bbf2736aa8964a4bee5d`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.20`

Release files / osu-1.5.4-py3-none-any.whl

Download URL	osu-1.5.4-py3-none-any.whl
Size	47.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`535923ce19a462e6706161109f9b89aaa862198a8edcbf27cddf311eb3f3d8a2`
BLAKE2b-256 checksum How to use checksums	`a89ad7dd9cfd27599eac268ac9d01a8d7f9f74687d48463d31d0ec68328f2138`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.20`