A bridge between Lichess Bot API and bots.
- NOTE: Only Python 3.7 or later is supported!
- Download the repo into lichess-bot directory.
- Navigate to the directory in cmd/Terminal:
cd lichess-bot
. - Install pip:
apt install python3-pip
. - Install virtualenv:
pip install virtualenv
. - Setup virtualenv:
apt install python3-venv
.
python3 -m venv venv # If this fails you probably need to add Python3 to your PATH.
virtualenv venv -p python3 # If this fails you probably need to add Python3 to your PATH.
source ./venv/bin/activate
python3 -m pip install -r requirements.txt
- Copy
config.yml.default
toconfig.yml
. - Edit the variants:
supported_variants
and time controls:supported_tc
from theconfig.yml
file as necessary.
- Here is a video on how to install the bot. Or you may proceed to the following steps.
- NOTE: Only Python 3.7 or later is supported!
- If you don't have Python, you may download it here. When installing it, enable "add Python to PATH", then go to custom installation (this may be not necessary, but on some computers it won't work otherwise) and enable all options (especially "install for all users"), except the last. It's better to install Python in a path without spaces, like "C:\Python".
- To type commands it's better to use PowerShell. Go to the Start menu and type "PowerShell" (you may use "cmd" too, but sometimes it may not work).
- Then you may need to upgrade pip. Execute
python3 -m pip install --upgrade pip
in PowerShell. - Download the repo into lichess-bot directory.
- Navigate to the directory in PowerShell:
cd [folder's address]
(example,cd C:\chess\lichess-bot
). - Install virtualenv:
pip install virtualenv
. - Setup virtualenv:
python3 -m venv .venv # If this fails you probably need to add Python3 to your PATH.
./.venv/Scripts/Activate.ps1 # `.\.venv\Scripts\activate.bat` should work in cmd in administrator mode. This may not work on Windows, and in this case you need to execute "Set-ExecutionPolicy RemoteSigned" first and choose "Y" there (you may need to run Powershell as administrator). After you execute the script, change execution policy back with "Set-ExecutionPolicy Restricted" and pressing "Y".
pip install -r requirements.txt
- Copy
config.yml.default
toconfig.yml
. - Edit the variants:
supported_variants
and time controls:supported_tc
from theconfig.yml
file as necessary (use "#" to disable certain ones).
- Create an account for your bot on Lichess.org.
- NOTE: If you have previously played games on an existing account, you will not be able to use it as a bot account.
- Once your account has been created and you are logged in, create a personal OAuth2 token with the "Play games with the bot API" ('bot:play') scope selected and a description added.
- A
token
(e.g.xxxxxxxxxxxxxxxx
) will be displayed. Store this in theconfig.yml
file as thetoken
field. You can also set the token in the environment variable$LICHESS_BOT_TOKEN
. - NOTE: You won't see this token again on Lichess, so do save it.
Within the file config.yml
:
- Enter the directory containing the engine executable in the
engine: dir
field. - Enter the executable name in the
engine: name
field (In Windows you may need to type a name with ".exe", like "lczero.exe") - If you want the engine to run in a different directory (e.g., if the engine needs to read or write files at a certain location), enter that directory in the
engine: working_dir
field.- If this field is blank or missing, the current directory will be used.
- Leave the
weights
field empty or see LeelaChessZero section for Neural Nets
As an optional convenience, there is a folder named engines
within the lichess-bot folder where you can copy your engine and all the files it needs. This is the default executable location in the config.yml.default
file.
Besides the above, there are many possible options within config.yml
for configuring the engine for use with lichess-bot.
protocol
: Specify which protocol your engine uses. Choices are"uci"
for the Universal Chess Interface"xboard"
for the XBoard/WinBoard/Chess Engine Communication Protocol"homemade"
if you want to write your own engine in Python within lichess-bot. See Creating a homemade bot below.
ponder
: Specify whether your bot will ponder--i.e., think while the bot's opponent is choosing a move.polyglot
: Tell lichess-bot whether your bot should use an opening book. Multiple books can be specified for each chess variant.enabled
: Whether to use the book at all.book
: A nested list of books. The next indented line should list a chess variant (standard
,3check
,horde
, etc.) followed on succeeding indented lines with paths to the book files. Seeconfig.yml.default
for examples.min_weight
: The minimum weight or quality a move must have if it is to have a chance of being selected. If a move cannot be found that has at least this weight, no move will be selected.selection
: The method for selecting a move. The choices are:"weighted_random"
where moves with a higher weight/quality have a higher probability of being chosen,"uniform_random"
where all moves of sufficient quality have an equal chance of being chosen, and"best_move"
where the move with the highest weight is always chosen.max_depth
: The maximum number of moves a bot plays before it stops consulting the book. Ifmax_depth
is 3, then the bot will stop consulting the book after its third move.
draw_or_resign
: This section allows your bot to resign or offer/accept draw based on the evaluation by the engine. XBoard engines can resign and offer/accept draw without this feature enabled.resign_enabled
: Whether the bot is allowed to resign based on the evaluation.resign_score
: The engine evaluation has to be less than or equal toresign_score
for the bot to resign.resign_for_egtb_minus_two
: If true the bot will resign in positions where the online_egtb returns a wdl of -2.resign_moves
: The evaluation has to be less than or equal toresign_score
forresign_moves
amount of moves for the bot to resign.offer_draw_enabled
: Whether the bot is allowed to offer/accept draw based on the evaluation.offer_draw_score
: The absolute value of the engine evaluation has to be less than or equal tooffer_draw_score
for the bot to offer/accept draw.offer_draw_for_egtb_zero
: If true the bot will offer/accept draw in positions where the online_egtb returns a wdl of 0.offer_draw_moves
: The absolute value of the evaluation has to be less than or equal tooffer_draw_score
foroffer_draw_moves
amount of moves for the bot to offer/accept draw.offer_draw_pieces
: The bot only offers/accepts draws if the position has less than or equal tooffer_draw_pieces
pieces.
online_moves
: This section gives your bot access to various online resources for choosing moves like opening books and endgame tablebases. This can be a supplement or a replacement for chess databases stored on your computer. There are three sections that correspond to three different online databases:chessdb_book
: Consults a Chinese chess position database, which also hosts a xiangqi database.lichess_cloud_analysis
: Consults Lichess' own position analysis database.online_egtb
: Consults either the online Syzygy 7-piece endgame tablebase hosted by Lichess or the chessdb listed above.
- Configurations common to all:
enabled
: Whether to use the database at all.min_time
: The minimum time in seconds on the game clock necessary to allow the online database to be consulted.
- Configurations only in
chessdb_book
andlichess_cloud_analysis
:move_quality
: Choice of"all"
(chessdb_book
only),"good"
, or"best"
.all
: Choose a random move from all legal moves.best
: Choose only the highest scoring move.good
: Choose randomly from the top moves. Inlichess_cloud_analysis
, the top moves list is controlled bymax_score_difference
. Inchessdb_book
, the top list is controlled by the online source.
min_depth
: The minimum search depth for a move evaluation for a database move to be accepted.
- Configurations only in
chessdb_book
:contribute
: Send the current board position to chessdb for later analysis.
- Configurations only in
lichess_cloud_analysis
:max_score_difference
: Whenmove_quality
is set to"good"
, this option specifies the maximum difference between the top scoring move and any other move that will make up the set from which a move will be chosen randomly. If this option is set to 25 and the top move in a position has a score of 100, no move with a score of less than 75 will be returned.min_knodes
: The minimum number of kilonodes to search. The minimum number of nodes to search is this value times 1000.
- Configurations only in
online_egtb
:max_pieces
: The maximum number of pieces in the current board for which the tablebase will be consulted.source
: One ofchessdb
orlichess
. Lichess also has tablebases for atomic and antichess while chessdb only has those for standard.
engine_options
: Command line options to pass to the engine on startup. For example, theconfig.yml.default
has the configuration
engine_options:
cpuct: 3.1
This would create the command-line option --cpuct=3.1
to be used when starting the engine, like this for the engine lc0: lc0 --cpuct=3.1
. Any number of options can be listed here, each getting their own command-line option.
uci_options
: A list of options to pass to a UCI engine after startup. Different engines have different options, so treat the options inconfig.yml.default
as templates and not suggestions. When UCI engines start, they print a list of configurations that can modify their behavior after receiving the string "uci". For example, to find out what options Stockfish 13 supports, run the executable in a terminal, typeuci
, and press Enter. The engine will print the following when run at the command line:
id name Stockfish 13
id author the Stockfish developers (see AUTHORS file)
option name Debug Log File type string default
option name Contempt type spin default 24 min -100 max 100
option name Analysis Contempt type combo default Both var Off var White var Black var Both
option name Threads type spin default 1 min 1 max 512
option name Hash type spin default 16 min 1 max 33554432
option name Clear Hash type button
option name Ponder type check default false
option name MultiPV type spin default 1 min 1 max 500
option name Skill Level type spin default 20 min 0 max 20
option name Move Overhead type spin default 10 min 0 max 5000
option name Slow Mover type spin default 100 min 10 max 1000
option name nodestime type spin default 0 min 0 max 10000
option name UCI_Chess960 type check default false
option name UCI_AnalyseMode type check default false
option name UCI_LimitStrength type check default false
option name UCI_Elo type spin default 1350 min 1350 max 2850
option name UCI_ShowWDL type check default false
option name SyzygyPath type string default <empty>
option name SyzygyProbeDepth type spin default 1 min 1 max 100
option name Syzygy50MoveRule type check default true
option name SyzygyProbeLimit type spin default 7 min 0 max 7
option name Use NNUE type check default true
option name EvalFile type string default nn-62ef826d1a6d.nnue
uciok
Any of the names following option name
can be listed in uci_options
in order to configure the Stockfish engine.
uci_options:
Move Overhead: 100
Skill Level: 10
The exceptions to this are the options uci_chess960
, uci_variant
, multipv
, and ponder
. These will be handled by lichess-bot after a game starts and should not be listed in config.yml
. Also, if an option is listed under uci_options
that is not in the list printed by the engine, it will cause an error when the engine starts because the engine won't understand the option. The word after type
indicates the expected type of the options: string
for a text string, spin
for a numeric value, check
for a boolean True/False value.
One last option is go_commands
. Beneath this option, arguments to the UCI go
command can be passed. For example,
go_commands:
nodes: 1
depth: 5
movetime: 1000
will append nodes 1 depth 5 movetime 1000
to the command to start thinking of a move: go startpos e2e4 e7e5 ...
.
xboard_options
: A list of options to pass to an XBoard engine after startup. Different engines have different options, so treat the options inconfig.yml.default
as templates and not suggestions. When XBoard engines start, they print a list of configurations that can modify their behavior. To see these configurations, run the engine in a terminal, typexboard
, press Enter, typeprotover 2
, and press Enter. The configurable options will be prefixed withfeature option
. Some examples may include
feature option="Add Noise -check VALUE"
feature option="PGN File -string VALUE"
feature option="CPU Count -spin VALUE MIN MAX"`
Any of the options can be listed under xboard_options
in order to configure the XBoard engine.
xboard_options:
Add Noise: False
PGN File: lichess_games.pgn
CPU Count: 1
The exceptions to this are the options multipv
, and ponder
. These will be handled by lichess-bot after a game starts and should not be listed in config.yml
. Also, if an option is listed under xboard_options
that is not in the list printed by the engine, it will cause an error when the engine starts because the engine won't know how to handle the option. The word prefixed with a hyphen indicates the expected type of the options: -string
for a text string, -spin
for a numeric value, -check
for a boolean True/False value.
One last option is go_commands
. Beneath this option, commands prior to the go
command can be passed. For example,
go_commands:
depth: 5
will precede the go
command to start thinking with sd 5
. The other go_commands
list above for UCI engines (nodes
and movetime
) are not valid for XBoard engines and will detrimentally affect their time control.
-
abort_time
: How many seconds to wait before aborting a game due to opponent inaction. This only applies during the first six moves of the game. -
fake_think_time
: Artificially slow down the engine to simulate a person thinking about a move. The amount of thinking time decreases as the game goes on. -
rate_limiting_delay
: For extremely fast games, the lichess.org servers may respond with an error if too many moves are played too quickly. This option avoids this problem by pausing for a specified number of milliseconds after submitting a move before making the next move. -
move_overhead
: To prevent losing on time due to network lag, subtract this many milliseconds from the time to think on each move. -
correspondence
These options control how the engine behaves during correspondence games.move_time
: How many seconds to think for each move.checkin_period
: How often (in seconds) to reconnect to games to check for new moves after disconnecting.disconnect_time
: How many seconds to wait after the bot makes a move for an opponent to make a move. If no move is made during the wait, disconnect from the game.ponder
: Whether the bot should ponder during the above waiting period.
-
challenge
: Control what kind of games for which the bot should accept challenges. All of the following options must be satisfied by a challenge to be accepted.concurrency
: The maximum number of games to play simultaneously.sort_by
: Whether to start games by the best rated/titled opponent"best"
or by first-come-first-serve"first"
.accept_bot
: Whether to accept challenges from other bots.only_bot
: Whether to only accept challenges from other bots.max_increment
: The maximum value of time increment.min_increment
: The minimum value of time increment.max_base
: The maximum base time for a game.min_base
: The minimum base time for a game.variants
: An indented list of chess variants that the bot can handle.
variants:
- standard
- horde
- antichess
# etc.
time_controls
: An indented list of acceptable time control types frombullet
tocorrespondence
.
time_controls:
- bullet
- blitz
- rapid
- classical
- correspondence
modes
: An indented list of acceptable game modes (rated
and/orcasual
).
modes:
-rated
-casual
greeting
: Send messages via chat to the bot's opponent. The string{me}
will be replaced by the bot's lichess account name. The string{opponent}
will be replaced by the opponent's lichess account name. Any other word between curly brackets will be removed. If you want to put a curly bracket in the message, use two:{{
or}}
.hello
: Message to send to the opponent before the bot makes its first move.goodbye
: Message to send to the opponent once the game is over.
greeting:
hello: Hi, {opponent}! I'm {me}. Good luck!
goodbye: Good game!
pgn_directory
: Write a record of every game played in PGN format to files in this directory. Each bot move will be annotated with the bot's calculated score and principal variation. The score is written with a tag of the form[%eval s,d]
, wheres
is the score in pawns (positive means white has the advantage), andd
is the depth of the search. Each game will be written to a uniquely named file.
pgn_directory: "game_records"
matchmaking
: Challenge a random bot.allow_matchmaking
: Whether to challenge other bots.challenge_variant
: The variant for the challenges. If set torandom
a variant from the ones enabled inchallenge.variants
will be chosen at random.challenge_timeout
: The time (in minutes) the bot has to be idle before it creates a challenge.challenge_initial_time
: The initial time (in seconds) for the challenges.challenge_increment
: The increment (in seconds) for the challenges.challenge_days
: The days for a correspondence challenge. If this option is enabled, a correspondence challenge will be created even ifchallenge_initial_time
is enabled.opponent_min_rating
: The minimum rating of the opponent bot. The minimum rating in lichess is 600.opponent_max_rating
: The maximum rating of the opponent bot. The maximum rating in lichess is 4000.challenge_mode
: Possible options arecasual
,rated
andrandom
.
matchmaking:
allow_matchmaking: false
challenge_variant: "random"
challenge_timeout: 30
challenge_initial_time: 60
challenge_increment: 3
# challenge_days: 2
opponent_min_rating: 600
opponent_max_rating: 4000
challenge_mode: "random"
WARNING: This is irreversible. Read more about upgrading to bot account.
- run
python3 lichess-bot.py -u
.
After activating the virtual environment created in the installation steps (the source
line for Linux and Macs or the activate
script for Windows), run
python3 lichess-bot.py
The working directory for the engine execution will be the lichess-bot directory. If your engine requires files located elsewhere, make sure they are specified by absolute path or copy the files to an appropriate location inside the lichess-bot directory.
To output more information (including your engine's thinking output and debugging information), the -v
option can be passed to lichess-bot:
python3 lichess-bot.py -v
If you want to record the output to a log file, add the -l
or --logfile
along with a file name:
python3 lichess-bot.py --logfile log.txt
- Press
CTRL+C
. - It may take some time to quit.
- Download the weights for the id you want to play from here.
- Extract the weights from the zip archive and rename it to
latest.txt
. - For Mac/Linux, build the lczero binary yourself following LeelaChessZero/lc0/README.
- Copy both the files into the
engine.dir
directory. - Change the
engine.name
andengine.engine_options.weights
keys inconfig.yml
file tolczero
andweights.pb.gz
. - You can specify the number of
engine.uci_options.threads
in theconfig.yml
file as well. - To start:
python3 lichess-bot.py
.
- For Windows modern CPUs, download the lczero binary from the latest Lc0 release (e.g.
lc0-v0.27.0-windows-cpu-dnnl.zip
). - Unzip the file, it comes with
lc0.exe
,dnnl.dll
, and a weights file example,703810.pb.gz
(amongst other files). - All three main files need to be copied to the engines directory.
- The
lc0.exe
should be doubleclicked and the windows safesearch warning about it being unsigned should be cleared (be careful and be sure you have the genuine file). - Change the
engine.name
key in theconfig.yml
file tolc0.exe
, no need to edit theconfig.yml
file concerning the weights file as thelc0.exe
will use whatever*.pb.gz
is in the same folder (have only one*pb.gz
file in the engines directory). - To start:
python3 lichess-bot.py
.
Use https://github.com/vochicong/lc0-nvidia-docker to easily run lc0 and lichess-bot inside a Docker container.
As an alternative to creating an entire chess engine and implementing one of the communication protocols (UCI
or XBoard
), a bot can also be created by writing a single class with a single method. The search()
method in this new class takes the current board and the game clock as arguments and should return a move based on whatever criteria the coder desires.
Steps to create a homemade bot:
- Do all the steps in the How to Install
- In the
config.yml
, change the engine protocol tohomemade
- Create a class in some file that extends
MinimalEngine
(instrategies.py
).- Look at the
strategies.py
file to see some examples. - If you don't know what to implement, look at the
EngineWrapper
orUCIEngine
class.- You don't have to create your own engine, even though it's an "EngineWrapper" class.
The examples just implementsearch
.
- You don't have to create your own engine, even though it's an "EngineWrapper" class.
- Look at the
- In the
config.yml
, change the name fromengine_name
to the name of your class-
In this case, you could change it to:
name: "RandomMove"
-
- You can specify a different config file with the
--config
argument. - Here's an example systemd service definition:
[Unit]
Description=lichess-bot
After=network-online.target
Wants=network-online.target
[Service]
Environment="PYTHONUNBUFFERED=1"
ExecStart=/usr/bin/python3 /home/thibault/lichess-bot/lichess-bot.py
WorkingDirectory=/home/thibault/lichess-bot/
User=thibault
Group=thibault
Restart=always
[Install]
WantedBy=multi-user.target
Thanks to the Lichess team, especially T. Alexander Lystad and Thibault Duplessis for working with the LeelaChessZero team to get this API up. Thanks to the Niklas Fiekas and his python-chess code which allows engine communication seamlessly.
lichess-bot is licensed under the AGPLv3 (or any later version at your option). Check out the LICENSE file for the full text.