Skip to main content

​
System Requirements

Before installing Guccho, ensure your system meets the following requirements:

Node.js

Version 22.17.1 or higher is required

Package Manager

pnpm 9.15.1 is recommended (npm and yarn also supported)
Guccho uses pnpm@9.15.1 as specified in the packageManager field. While other package managers work, pnpm is recommended for optimal dependency management.

​
Additional Requirements

Depending on your backend configuration, you’ll also need:
  • MySQL: For database storage (bancho.py and ppy.sb backends)
  • Redis: For session storage and leaderboards (optional but recommended)
  • Private osu! server: A running instance of bancho.py or ppy.sb

​
Installing Dependencies

1

Clone the repository

First, clone the Guccho repository to your local machine:
git clone https://github.com/ppy-sb/guccho.git
cd guccho
2

Install Node.js

Download and install Node.js 22.17.1 or higher from nodejs.org.Verify your installation:
node --version
# Should output v22.17.1 or higher
3

Install pnpm (recommended)

If you don’t have pnpm installed, install it globally:
npm install -g pnpm@9.15.1
Verify the installation:
pnpm --version
# Should output 9.15.1
4

Install project dependencies

Install all required dependencies using your preferred package manager:
pnpm install
The postinstall script will automatically run build generation tasks and prepare Nuxt.

​
Setting Up Database Tools (Optional)

If you’re using the bancho.py or ppy.sb@bancho.py backend, you can enable Drizzle ORM tooling:
Make sure to set the DB_DSN environment variable before running database-related commands.
export DB_DSN="mysql://username:password@localhost:3306/database"
This enables features like database migrations and schema introspection.

​
Verifying Installation

To verify that everything is installed correctly: 
pnpm typecheck
If the command completes without errors, your installation is successful!

​
Next Steps

Quick Start

Continue to the Quick Start guide to configure and run Guccho