README.md

July 13, 2026 ยท View on GitHub

www.pychess.org

Python-CI Nodejs-CI Discord Ask DeepWiki

pychess-variants.png

Pychess-variants is a free, open-source chess server designed to play chess variants.

Currently supported games are listed on https://www.pychess.org/variants

For move generation, validation, analysis and engine play it uses:

On client side it is based on chessgroundx fork of chessground

As you know, pychess-variants is a free server and it will remain free forever. However, maintaining and improving the server costs time and money.

If you like our work and find our server useful, please donate through Patreon or directly through paypal !! Your contribution will be greatly appreciated and help me continue to develop this awesome server.

Installation

Prerequisites

Project setup

# Sync Python dependencies into the project virtualenv
uv sync --extra dev

# Optionally activate the virtualenv for interactive work
source .venv/bin/activate

yarn install                            # Install node requirements
yarn dev                                # Compile typescript files to javascript
yarn md                                 # Compile md files to html

All Python commands below should be run with uv run ... unless you have already activated .venv.

The project now targets Python 3.14+.

TypeScript and JavaScript checks

yarn format
yarn check-format
yarn lint
yarn typecheck
yarn test

Start server

uv run server/server.py

Python checks and tests

uv run ruff format .
uv run ruff check .
uv run pyright
env PYTHONPATH=server uv run python -m unittest discover -s tests
env PYTHONPATH=server:tests uv run python -m unittest tests.some_test_module
uv run python -m playwright install
env PYTHONPATH=server uv run python -m pytest tests/test_e2e.py
env PYTHONPATH=server uv run python -m pytest tests/test_gui.py

Docker setup

If you want to avoid installing dependencies (mongo, node, python) you can instead run the server locally in docker using compose. To start it, simply run:

docker compose up --build

This recompiles the frontend and starts the server and DB. Once it is up, you can connect to localhost:8080 in your browser. For more detailed Docker workflows, including contributor checks and the optional ci service, see docker/README.md.

Supported browsers

Pychess-variants should support almost all browsers. Though older browsers (including any version of Internet Explorer) will not work. For your own sake, please upgrade. Security and performance, think about it!

Only Fairy-Stockfish analysis might not work on all browsers.