What is the OSZ file format?
An .osz file is a beatmap package for osu!, the free rhythm game developed by Dean Herbert (peppy) and distributed by ppy Pty Ltd. Structurally, an .osz file is a standard ZIP archive renamed with the .osz extension - renaming it back to .zip and opening it with any archive tool reveals the contents immediately.
Inside a typical .osz package you will find:
- One or more
.osubeatmap definition files (UTF-8 text, internal format version 14) - An audio track, usually
.mp3or.ogg - A background image (
.pngor.jpg) - Optional storyboard scripts and custom hitsound
.wavor.oggsamples
When the osu! client opens an .osz file it automatically extracts the archive into the Songs folder and registers all included difficulty levels. Beatmaps are distributed through the osu! website; clicking a download link there triggers the client to import the file directly. The osu!lazer client, which reached stable status in 2024, also accepts .osz imports across Windows, macOS, Linux, Android, and iOS.
Integrity is verified using CRC-32 checksums per ZIP entry and MD5 hashes per .osu file, the latter used to validate scores submitted to the online ranking system. Package sizes typically range from 2 MB to 150 MB depending on audio length and the number of included difficulty levels.
Security & safety
RISK: LOWOSZ files contain audio, images, and plain-text .osu files only - no executables. Low risk. Download only from the official osu.ppy.sh site to avoid tampered files. Community mirror sites sometimes bundle .osz files with adware-laden downloaders - use the official osu! client's in-game download or the official website.
Format details
in a nutshellPrograms that open OSZ files
Windows2 apps
osu!
Free Double-click the .osz file; osu! automatically imports and extracts it to the Songs folder. 
7-Zip
Open-source Right-click → Open archive (treat as ZIP) to inspect contents without installing osu!. 
macOS1 app
Linux1 app
osu! (lazer)
Free Download osu!lazer AppImage or package; import .osz via the game's import function. 
Android1 app
osu!lazer (Android)
Free Install osu!lazer from Google Play or osu! site; open the .osz file to import.
osu!lazer (iOS)
Free Install osu!lazer from the App Store; use Files app to open .osz and hand off to osu!lazer. Technical details
deep spec| Container format | Standard ZIP archive; magic bytes `50 4B 03 04` at offset 0, identical to any `.zip` file |
| Internal beatmap format | `.osu` UTF-8 text files; current internal format version 14 (since 2013); older maps may use versions 9-13 |
| Audio encoding | MP3 (128-320 kbps) or OGG Vorbis (128-192 kbps) typical; no strict encoding limit enforced by the format |
| Image format | PNG or JPEG for background art; no enforced resolution limit |
| Compression | DEFLATE per-entry (ZIP); audio and image files are often stored using ZIP STORED method (uncompressed) |
| Beatmap integrity | MD5 hash per `.osu` file used for online ranking validation; CRC-32 per ZIP entry (standard ZIP) |
| Typical package size | 2 MB - 150 MB depending on audio length and number of included difficulty levels |
| Typical file count | 10-50 files per package: one `.osu` per difficulty level plus shared audio, background, and hitsound assets |
| MIME type | `application/x-osu-beatmap-archive` (osu! client registered); `application/zip` also accepted |
| Platform support | Windows, macOS, Linux (osu!stable and osu!lazer); Android and iOS (osu!lazer, stable since 2024) |
| Import behaviour | osu! client auto-extracts to Songs folder on file open; no manual extraction required by the user |
| Optional storyboard | `.osb` storyboard script or inline storyboard section in `.osu`; custom scripting language for animations and effects |
| Hitsound samples | WAV or OGG audio files bundled in the package; override default game sounds per beatmap |
| Byte order | Little-endian (standard ZIP structure) |
| Released | 2007 (osu! initial release, September 2007) |
| Latest version | N/A (format has not been versioned externally; osu! file format v14 internally for .osu files) |
| Specification | osu.ppy.sh |
OSZ conversions
Community Q&A
asked by usersNo questions yet - be the first to ask about OSZ files.
