Run Lichess Locally: Full Chess Server on Your Machine

// Before you start

What you need

Linux or macOS (Windows is not officially supported)
Git installed
Java 21+ installed (check with: java -version)
MongoDB 6+ installed and running
Node.js 20+ and pnpm installed
At least 8 GB RAM and 10 GB free disk space

Step 1 of 6

Clone the repo and its submodules

5 min

Lila depends on several sub-projects (like scalachess) that live in separate repositories. The --recurse-submodules flag pulls all of them in one shot so nothing is missing.

Terminal · mac

$ git clone --recurse-submodules https://github.com/lichess-org/lila.git && cd lila

What you should see

A folder called 'lila' appears. The last lines say 'Submodule path ... registered' for several sub-repos.

This might happen

Clone finishes but submodule folders are empty

Run: git submodule update --init --recursive

Step 2 of 6

Install the UI build dependencies

5 min

The web front-end is TypeScript and Sass. Lila ships a helper script that installs all JavaScript/CSS tooling via pnpm. You must have pnpm available globally first.

Terminal · mac

$ npm install -g pnpm && ./ui/build

What you should see

pnpm installs packages, then the build script compiles TypeScript and Sass. Final line is something like 'Done in Xs.'

This might happen

'pnpm: command not found' after install

Close and reopen your terminal, or run: source ~/.bashrc (Linux) / source ~/.zshrc (macOS)

Step 3 of 6

Start MongoDB and seed the database

5 min

Lila stores everything in MongoDB. You need it running before the server starts. The Wiki provides a small seed script that creates the required collections and an admin user.

Terminal · mac

$ mongod --fork --logpath /tmp/mongod.log --dbpath /tmp/lila-db && mkdir -p /tmp/lila-db

What you should see

Terminal prints: 'child process started successfully, parent exiting'

This might happen

'Data directory /tmp/lila-db not found' error

Run mkdir -p /tmp/lila-db first, then retry the mongod command

Step 4 of 6

Copy and review the application config

3 min

Lila reads its settings from a file called application.conf. A sample file is included. You copy it into place and, at minimum, confirm the MongoDB URI matches where your database is running. This is the one file you may need to open in a text editor.

Terminal · mac

$ cp conf/application.conf.default conf/application.conf

What you should see

No output. A new file conf/application.conf now exists.

This might happen

Server later fails with 'Configuration error: mongodb'

Open conf/application.conf in any text editor and confirm the line mongodb.uri = "mongodb://127.0.0.1:27017/lichess" is present and unchanged

Step 5 of 6

Compile and start the Lila server

15-30 min

lila.sh is a thin wrapper around sbt, the Scala build tool. The first run downloads the Scala compiler and all library dependencies — this takes a long time. Subsequent starts are much faster. Once you see 'Listening for HTTP on', the server is ready.

Terminal · mac

$ ./lila.sh run

What you should see

After a long compile phase you see a line like: [info] p.c.s.NettyServer - Listening for HTTP on /0:0:0:0:0:0:0:0:9663

This might happen

Out of memory error during compilation (Java heap space)

Run: export SBT_OPTS='-Xmx2g -Xms512m' then retry ./lila.sh run

Step 6 of 6

Open Lichess in your browser

1 min

With the server running, open your browser and go to localhost. You should see a local copy of the Lichess homepage. You can register a local account and start playing against yourself or a bot.

Terminal · mac

$ open http://localhost:9663

What you should see

The Lichess homepage loads in your browser with the familiar board and navigation.

This might happen

Page loads but CSS is missing or looks broken

The UI build may not have finished. Re-run ./ui/build in a second terminal while the server is running, then hard-refresh the browser (Ctrl+Shift+R)

// Status

cooked. baked. worked.

A locally running copy of the Lichess chess server accessible at http://localhost:9663, where you can register an account, create games, and use core features — without needing internet access or touching the real lichess.org.

// the honest bit

The honest part

This is a serious developer-grade project. The full production stack (Elasticsearch, Redis, fishnet AI cluster, nginx) is NOT set up by this guide — you get a minimal playable server only. Computer analysis and some search features will not work without those extra services. The first compile genuinely takes 20-30 minutes and requires a capable machine. Windows is not supported. Non-developers should expect to consult the official Wiki (github.com/lichess-org/lila/wiki) when things go wrong.