fairyfishnet

PyPI version

Distributed Fairy-Stockfish analysis for pychess.org.

fairyfishnet requires Python 3.10 or newer.

Installation

  1. Request a personal fairyfishnet key on the pychess Discord server.

  2. Install uv.

  3. Install the worker as an isolated command-line tool:

    uv tool install --with pip fairyfishnet

  4. 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
  • Cores is the total number of engine threads. auto uses all but one logical CPU, while all uses every logical CPU reported by Python.
  • Threads is a hint for the number of threads per engine process. Its default is 3, or fewer when fewer cores are selected.
  • Memory is the total Fairy-Stockfish transposition-table (UCI Hash) 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.

Engine lifecycle, UCI, dynamic variant, and cache 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 pyright
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.

Sequence diagram

Releasing

Set UV_PUBLISH_TOKEN, then run:

uv run python scripts/release.py

The release helper runs tests, Ruff, Pyright, 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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for btami from gravatar.com btami Avatar for Fulmene from gravatar.com Fulmene

Credits

Author: Bajusz Tamás

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.10

Tags

chess fairy-stockfish fishnet pychess uci

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fairyfishnet-1.16.70.tar.gz (174.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

fairyfishnet-1.16.70-py3-none-any.whl (50.8 kB view details)

Uploaded Python 3

File details

Details for the file fairyfishnet-1.16.70.tar.gz.

File metadata

  • Download URL: fairyfishnet-1.16.70.tar.gz
  • Upload date:
  • Size: 174.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.1

File hashes

Hashes for fairyfishnet-1.16.70.tar.gz
Algorithm Hash digest
SHA256 df70b84b318546b6946031999cb43382a1f448980b92d4ffc27991486d1251e4
MD5 cf35fe3223e109e62716796be5df444f
BLAKE2b-256 54a05c9a27d1c0f6ceea71c2503396142ffad1228ac2be2416b66627761271a2

See more details on using hashes here.

File details

Details for the file fairyfishnet-1.16.70-py3-none-any.whl.

File metadata

  • Download URL: fairyfishnet-1.16.70-py3-none-any.whl
  • Upload date:
  • Size: 50.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.1

File hashes

Hashes for fairyfishnet-1.16.70-py3-none-any.whl
Algorithm Hash digest
SHA256 99ea47639efdf37e007c3a2f98e68a577ffff9166f3d9bbafa1968af508afab8
MD5 6fd0952ca13af506fe3b3ccfb2ec84fd
BLAKE2b-256 55e7d5ebf919c2f94235844cbfbf4f47d2e1ee0804ef583a1bac243c657ef563

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.16.70 This release

2 files

1.16.69

2 files

1.16.64

2 files

1.16.62

2 files

1.16.61

2 files

1.16.60

2 files

1.16.59

2 files

1.16.58

2 files

1.16.57

2 files

1.16.56

2 files

1.16.55

2 files

1.16.54

2 files

1.16.53

2 files

1.16.52

2 files

1.16.50

2 files

1.16.49

2 files

1.16.48

2 files

1.16.47

2 files

1.16.46

2 files

1.16.45

2 files

1.16.44

2 files

1.16.43

2 files

1.16.42

2 files

1.16.41

2 files

1.16.40

2 files

1.16.39

2 files

1.16.38

2 files

1.16.37

2 files

1.16.36

2 files

1.16.35

2 files

1.16.34

2 files

1.16.33

2 files

1.16.32

2 files

1.16.30

2 files

1.16.29

2 files

1.16.28

2 files

1.16.27

2 files

1.16.26

2 files

1.16.25

2 files

1.16.24

2 files

1.16.23

2 files

1.16.22

2 files

1.16.21

2 files

1.16.20

2 files

1.16.19

2 files

1.16.18

2 files

1.16.17

2 files

1.16.16

2 files

1.16.15

2 files

1.16.14

2 files

1.16.13

2 files

1.16.12

2 files

1.16.11

2 files

1.16.10

2 files

1.16.9

2 files

1.16.8

2 files

1.16.7

2 files

1.16.6

2 files

1.16.5

2 files

1.16.4

2 files

1.16.3

2 files

1.16.2

2 files

1.16.1

2 files

1.16.0

2 files

1.15.52

2 files

1.15.51

2 files

1.15.50

2 files

1.15.49

2 files

1.15.48

2 files

1.15.47

2 files

1.15.46

2 files

1.15.45

2 files

1.15.44

2 files

1.15.43

2 files

1.15.42

2 files

1.15.41

2 files

1.15.40

2 files

1.15.39

2 files

1.15.38

2 files

1.15.37

2 files

1.15.36

2 files

1.15.35

2 files

1.15.34

2 files

1.15.33

2 files

1.15.32

2 files

1.15.31

2 files

1.15.30

2 files

1.15.29

2 files

1.15.28

2 files

1.15.27

2 files

1.15.26

2 files

1.15.25

2 files

1.15.24

2 files

1.15.23

2 files

1.15.22

2 files

1.15.21

2 files

1.15.20

2 files

1.15.19

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page