Integrate a Third NNUE in Wordfish

Integrate a Third NNUE Network in Wordfish (FalconFile)

0) What you’ll need

• A recent Wordfish binary built with NNUE support.
• The NNUE weight file you want to use as the third network. In this guide we call it 3.net (you can use any filename; FalconFile lets you point to it).
• File system access to place the network near the engine or anywhere readable.

Note: There is no 3.net in the Wordfish repository. You must obtain an NNUE weight from a trusted source (e.g., official Stockfish network releases). Then either keep its original filename or rename it to 3.net if you like the convention.

1) Obtain the network file

Windows (PowerShell)

# Example: download to current folder and name it 3.net
Invoke-WebRequest -Uri "<ACTUAL-NETWORK-URL>" -OutFile "3.net"

# Example: download to current folder and name it 3.net
Invoke-WebRequest -Uri "<ACTUAL-NETWORK-URL>" -OutFile "3.net"

Windows (CMD)

curl -L "<ACTUAL-NETWORK-URL>" -o 3.net

curl -L "<ACTUAL-NETWORK-URL>" -o 3.net

Linux / macOS

wget "<ACTUAL-NETWORK-URL>" -O 3.net
# or
curl -L "<ACTUAL-NETWORK-URL>" -o 3.net

wget "<ACTUAL-NETWORK-URL>" -O 3.net
# or
curl -L "<ACTUAL-NETWORK-URL>" -o 3.net

• Replace <ACTUAL-NETWORK-URL> with the real link to the NNUE weight you want.
• If the file doesn’t naturally end with .net or .nnue, it’s fine—Wordfish only needs the correct path. The name 3.net is just a practical label.

(Optional) Verify checksum
If the source publishes a checksum:

# Linux/macOS
sha256sum 3.net
# Windows PowerShell
Get-FileHash .\3.net -Algorithm SHA256

# Linux/macOS
sha256sum 3.net
# Windows PowerShell
Get-FileHash .\3.net -Algorithm SHA256

Compare the output with the published hash.

2) Place the network file

You have two common choices:

• Same folder as the engine executable (simple, portable).
• Anywhere on disk, and you’ll pass an absolute path to FalconFile.

Examples:

• C:\Engines\Wordfish\wordfish.exe and C:\Engines\Wordfish\3.net
• /home/user/engines/wordfish/wordfish and /home/user/engines/wordfish/3.net

3) Tell Wordfish to use the network (UCI FalconFile)

A) Plain console (quick sanity check)

Start the engine, switch to UCI mode, set the option, and verify readiness.

Windows (CMD / PowerShell):

wordfish.exe
uci
setoption name FalconFile value 3.net
isready

wordfish.exe
uci
setoption name FalconFile value 3.net
isready

Linux / macOS:

./wordfish
uci
setoption name FalconFile value 3.net
isready

./wordfish
uci
setoption name FalconFile value 3.net
isready

• If 3.net isn’t in the same directory, pass a full path: setoption name FalconFile value C:\Engines\Wordfish\networks\3.net or setoption name FalconFile value /home/user/engines/wordfish/networks/3.net
• After isready, the engine should respond with readyok. Many builds also print an info string indicating the network file it loaded. That’s a good sign you’re using the intended model.

B) CuteChess-CLI

cutechess-cli \
  -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" option.Hash=256 option.Threads=8 \
  -engine cmd="C:\Engines\Other\opponent.exe" option.Hash=256 option.Threads=8 \
  -each tc=10+0.1 -rounds 50 -concurrency 8

cutechess-cli \
  -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" option.Hash=256 option.Threads=8 \
  -engine cmd="C:\Engines\Other\opponent.exe" option.Hash=256 option.Threads=8 \
  -each tc=10+0.1 -rounds 50 -concurrency 8

Tip: In CuteChess-CLI, engine options are specified as option.<UCIName>=<value>.

C) FastChess

fastchess.exe ^
  -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" option.Hash=256 option.Threads=8 ^
  -engine cmd="C:\Engines\Other\opponent.exe" option.Hash=256 option.Threads=8 ^
  -each tc=10+0.1 -rounds 50 -concurrency 8

fastchess.exe ^
  -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" option.Hash=256 option.Threads=8 ^
  -engine cmd="C:\Engines\Other\opponent.exe" option.Hash=256 option.Threads=8 ^
  -each tc=10+0.1 -rounds 50 -concurrency 8

Important: Use the option.<UCIName>=<value> form in FastChess (e.g., option.FalconFile=3.net). Don’t use initstr; FastChess does not accept that parameter.

D) Common desktop GUIs

• BanksiaGUI / Arena / Cute Chess GUI / Fritz / ChessBase:
  Add Wordfish as a UCI engine → open Engine Options → find FalconFile → set to your 3.net (or browse to an absolute path).
  Save/apply and (re)start the engine.

4) Make it persistent

Most GUIs remember engine options after you set them once. For CLI usage, keep the option.FalconFile=... clause in your scripts so future runs automatically load the same network.

5) Verify the network is actually in use

• On engine start (after uci), set FalconFile, then run: isready ucinewgame position startpos go depth 1 Engines commonly print an info string on load or fail loudly if the file is missing.
• If you maintain multiple networks, deliberately point to a nonexistent file once to ensure the engine throws an error—this confirms the option is active and not ignored.

6) Typical directory layout (portable)

Wordfish/
├─ wordfish.exe
├─ 3.net
├─ books/
│  └─ mybook.bin
└─ logs/

Wordfish/
├─ wordfish.exe
├─ 3.net
├─ books/
│  └─ mybook.bin
└─ logs/

This keeps the network alongside the binary so FalconFile value 3.net works without absolute paths.

7) Troubleshooting

Q: FalconFile is not listed in UCI options.
A: Update to a Wordfish build that includes the option and NNUE support, then check again with uci. (Some forks expose EvalFile or similar; Wordfish exposes FalconFile per this guide.)

Q: The engine ignores my file or falls back to another net.

• Ensure the path is correct. Quote paths with spaces: option.FalconFile="C:\Users\Me\Desktop\nets\my third net.nnue"
• Prefer an absolute path for testing.
• Confirm file permissions (readable by your user).

Q: “File not found” or “cannot open.”

• Double-check the filename and extension.
• Place the file next to the executable and try just 3.net to rule out path issues.

Q: Crash or “invalid network” errors.

• The file may be corrupt or not a supported NNUE format for your build—download again from a trusted source and verify hash.

Q: Performance seems unchanged.

• Confirm the engine actually loaded the requested file (watch for load messages, or point to an obviously wrong name to provoke an error).
• Some GUIs cache options—close the GUI, delete its engine profile, re-add Wordfish, then set FalconFile again.

8) Ready-to-use command snippets

Windows – test quickly in place

cd /d C:\Engines\Wordfish
wordfish.exe
uci
setoption name FalconFile value 3.net
isready
ucinewgame
position startpos
go depth 10

cd /d C:\Engines\Wordfish
wordfish.exe
uci
setoption name FalconFile value 3.net
isready
ucinewgame
position startpos
go depth 10

CuteChess-CLI – 1v1 match (Windows)

cutechess-cli -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" -engine cmd="C:\Engines\Other\opponent.exe" -each tc=10+0.1 -rounds 50 -concurrency 8

cutechess-cli -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" -engine cmd="C:\Engines\Other\opponent.exe" -each tc=10+0.1 -rounds 50 -concurrency 8

FastChess – 1v1 match (Windows)

fastchess.exe -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" -engine cmd="C:\Engines\Other\opponent.exe" -each tc=10+0.1 -rounds 50 -concurrency 8

fastchess.exe -engine cmd="C:\Engines\Wordfish\wordfish.exe" option.FalconFile="C:\Engines\Wordfish\3.net" -engine cmd="C:\Engines\Other\opponent.exe" -each tc=10+0.1 -rounds 50 -concurrency 8

Linux/macOS – quick check

cd ~/engines/wordfish
./wordfish
uci
setoption name FalconFile value ./3.net
isready

cd ~/engines/wordfish
./wordfish
uci
setoption name FalconFile value ./3.net
isready

9) (Optional) Keep multiple nets and switch on demand

You can store several nets and point FalconFile to the one you want:

nets/
  ├─ 1.net
  ├─ 2.net
  └─ 3.net

nets/
  ├─ 1.net
  ├─ 2.net
  └─ 3.net

Then:

setoption name FalconFile value /absolute/path/to/nets/3.net

setoption name FalconFile value /absolute/path/to/nets/3.net

If your GUI supports engine profiles, create one profile per network for one-click switching.

10) Safety & provenance

• Only use trusted NNUE weights (verify checksums when provided).
• If you distribute your engine bundle, do not assume you’re allowed to re-host third-party nets—link to the source and include licensing/attribution as required by the network’s publisher.

TL;DR

1. Download your desired NNUE → save/rename as 3.net.
2. Put it next to wordfish.exe (or note its absolute path).
3. Set FalconFile to that file:

setoption name FalconFile value 3.net

setoption name FalconFile value 3.net

4. Verify with isready and a quick go depth 1.
5. In CLI tools, pass it as option.FalconFile=....

You’re done—Wordfish will now evaluate with your third network.

Jorge Ruiz

connoisseur of both chess and anthropology, a combination that reflects his deep intellectual curiosity and passion for understanding both the art of strategic chess books

SÍGUEME