fairyfishnet
Distributed Fairy-Stockfish analysis for pychess.org.
fairyfishnet requires Python 3.10 or newer.
Installation
-
Request a personal fairyfishnet key on the pychess Discord server.
-
Install uv.
-
Install the worker as an isolated command-line tool:
uv tool install --with pip fairyfishnet -
Start the worker and follow the configuration prompts:
fairyfishnet --auto-update
To upgrade manually:
uv tool upgrade fairyfishnet
The extra pip package keeps the worker's existing --auto-update behavior available inside the isolated uv tool environment.
systemd
Generate a service file after configuring the worker:
fairyfishnet systemd
The command prints a service definition that can be reviewed and installed under /etc/systemd/system/.
Docker
Build the image. The Dockerfile installs the latest released fairyfishnet package from PyPI; it does not install the current checkout:
docker build -t fairyfishnet .
docker run --rm fairyfishnet --key MY_API_KEY --auto-update
Resource allocation
The [Fishnet] section of fishnet.ini controls how the selected logical CPU cores and engine hash memory are divided among Fairy-Stockfish processes:
[Fishnet]
Cores = 4
Threads = 2
Memory = 256
Coresis the total number of engine threads.autouses all but one logical CPU, whilealluses every logical CPU reported by Python.Threadsis a hint for the number of threads per engine process. Its default is 3, or fewer when fewer cores are selected.Memoryis the total Fairy-Stockfish transposition-table (UCIHash) budget in MB across all engine processes. It is not a limit for total process RAM and is not calculated from available system memory.
The number of engine processes is max(1, Cores // Threads). All selected cores are then distributed as evenly as possible among those processes, so the actual thread count can be slightly higher than the Threads hint. Memory = auto assigns 256 MB of hash per process. A manual value is divided among the processes and must provide each one between 16 and 512 MB of hash.
For example, an 8-thread machine with Cores = auto selects 7 cores:
Threads |
Engine processes | Actual engine threads | Memory = auto |
|---|---|---|---|
auto or 3 |
2 | 4 + 3 | 512 MB total |
2 |
3 | 3 + 2 + 2 | 768 MB total |
1 |
7 | 1 each | 1792 MB total |
The example configuration above starts two 2-thread engines and gives each engine 128 MB of hash. Operating-system memory usage will be higher because each process also uses memory for the engine, NNUE networks, thread state, and other data. More pages may become resident while an engine is searching.
Fewer threads per process allow more concurrent jobs and generally favor total queue throughput. More threads per process reduce concurrency but can lower the latency of an individual job. fairyfishnet uses this static allocation for its lifetime; it does not dynamically move cores between busy and idle engines.
The equivalent command-line options are --cores, --threads-per-process, and --memory.
Fairy-Stockfish
fairyfishnet uses the pychess-variants build of Fairy-Stockfish.
A suitable precompiled engine is downloaded automatically. To use a locally built engine, run ./build-stockfish.sh and pass its path with --stockfish-command.
Optional Alice-Stockfish
Alice Chess can use the dedicated Alice-Stockfish engine while all other variants continue to use Fairy-Stockfish. This support is optional: configure AliceStockfishCommand in [Fishnet] (or pass --alice-stockfish-command) only on workers that have a compatible Alice-Stockfish executable.
[Fishnet]
AliceStockfishCommand = /path/to/alice-stockfish
[AliceStockfish]
# Optional UCI settings specific to Alice-Stockfish.
# EvalFile = /path/to/Alice_v1.nnue
At startup fairyfishnet checks that the executable starts, advertises the alice UCI variant, accepts the configured [AliceStockfish] options, and completes a shallow search. If any of those checks fail, Alice support is disabled for that worker while normal Fairy-Stockfish work continues. Workers without Alice support do not advertise the Alice capability, so the server will not assign them Alice jobs.
Each worker process still owns only one engine subprocess at a time. It switches from Fairy-Stockfish to Alice-Stockfish when it receives Alice work and back to Fairy-Stockfish for other variants, avoiding an extra idle engine process per worker.
Engine routing and optional-capability invariants are documented in ENGINES.md.
Development
The repository uses a src/ package layout and keeps tests under tests/.
Create the locked development environment using the oldest supported Python:
uv sync --locked --python 3.10
Run the fast tests and quality checks:
uv run pytest -m "not engine"
uv run ruff check .
uv run ruff format --check .
uv run pyrefly check
uv lock --check --python 3.10
uv build
The engine integration tests download or launch Fairy-Stockfish:
uv run pytest -m engine
Apply formatting with:
uv run ruff format .
Whenever project or development dependencies change, refresh and commit the lockfile:
uv lock
Repository layout
src/fairyfishnet/__init__.py package metadata only
src/fairyfishnet/cli.py argument parsing, commands, signals, and worker orchestration
src/fairyfishnet/config.py configuration loading and validation
src/fairyfishnet/engine.py subprocess management and the UCI protocol
src/fairyfishnet/worker.py job acquisition, move generation, and analysis
src/fairyfishnet/variants.py server variants.ini download and scoped cache lifecycle
src/fairyfishnet/downloads.py engine downloads and self-update handling
src/fairyfishnet/cpuid.py low-level CPU capability probing
src/fairyfishnet/http_utils.py HTTP and release-version helpers
tests/ focused unit tests and engine integration tests
scripts/ release and maintenance helpers
doc/ fishnet protocol documentation
The fast suite is intentionally split by subsystem, so a regression normally points to the module that owns the behavior. Tests marked engine download or launch Fairy-Stockfish and are therefore slower and require network access on a clean checkout.
Protocol
See doc/protocol.md for the worker/server protocol.
Releasing
Set UV_PUBLISH_TOKEN, then run:
uv run python scripts/release.py
The release helper runs tests, Ruff, Pyrefly, builds distributions, verifies a clean Git tree, creates the version tag, pushes it, and publishes with uv.
License
fairyfishnet is licensed under GPL-3.0-or-later. See LICENSE.txt.
Release files for fairyfishnet 1.16.74
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| fairyfishnet-1.16.74.tar.gz | 180.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fairyfishnet-1.16.74-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 233.9 kB
Release files / fairyfishnet-1.16.74.tar.gz
| Download URL | fairyfishnet-1.16.74.tar.gz |
|---|---|
| Size | 180.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71ae6a0e80760ca9a26dacc097cd9f45a3318b31496aec86de9ce336ee4d93a1
|
|
BLAKE2b-256 checksum How to use checksums |
3ff21992732e819bd029ca58960df7fc2fec67bf61c63cb6956cb2f53a39f900
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.1
|
Release files / fairyfishnet-1.16.74-py3-none-any.whl
| Download URL | fairyfishnet-1.16.74-py3-none-any.whl |
|---|---|
| Size | 53.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e1c43411662245c92ac66ec09a0035f637f8b6a8144a33b11a781bf36feeae9
|
|
BLAKE2b-256 checksum How to use checksums |
6db6bdb6b212ac0cb3a6c1af44475a8114a396a4499d175b541079e4a5c76e31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.1
|
Security for fairyfishnet 1.16.74
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
