Welcome to parsecore

parsecore is a modern, easy to use, feature-rich Python library for osu! beatmap parsing, mod handling, and performance-point calculation.

Features:

• Bit-exact with the official osu! implementation — currently the 2026 Q2 pp/star-rating rework (2026.702.1)

• Star rating and performance points for all four rulesets (osu!, osu!taiko, osu!catch, osu!mania)

• Faithful osu! → taiko / catch / mania converts

• Complete mod model — lazer and legacy mods, acronyms, settings

• Fully typed, mypy-checked, dependency-light pure-Python core

Getting started

Is this your first time using the library? This is the place to get started!

• First steps: Installation | Quickstart

• Working with beatmaps: Parsing | Star rating | Performance points

• Going further: Converts | Mods

Getting help

If you’re having trouble with something, these resources might help.

• Read the guide to how pp calculation works.

• Wondering why results differ from other tools? See Bit-exactness & parity and Lazer vs stable scoring.

• Try the search, or browse the API reference below.

• Report bugs in the issue tracker.

Manuals

These pages go into great detail about everything the library can do.

• Beatmap API — parsing, sections, hit objects, encoding

• Mods API — mods, acronyms, game modes

• Performance API — difficulty and performance calculation

Meta

If you’re looking for something related to the project itself, it’s here.

• Versioning & algorithm tracking — how parsecore follows osu! updates

• Changelog — the changelog for the library