Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A basic chess model to imports/export FEN & finds moves.

Project Description

Chessnut is a simple chess board model written in Python. Chessnut is not a chess engine – it has no AI to play games, and it has no GUI. It is a simple package that can import/export games in Forsyth-Edwards Notation (FEN), generate a list of legal moves for the current board position, intelligently validate & apply moves (including en passant, castling, etc.), and keep track of the game with a history of both moves and corresponding FEN representation.

Chessnut is not written for speed, it is written for simplicity (there are only two real classes, and only about 200 lines of code). By adding a custom move evaluation function, Chessnut could be used as a chess engine. The simplicity of the model lends itself well to studying the construction of a chess engine without worrying about implementing a chess model, or to easily find the set of legal moves for either player on a particular chess board for use in conjunction with another chess application.



Chessnut can be used as a module within your project or it can be installed on your system as a package. If you’re going to install it as a package, you should consider using Virtualenv to manage your python environment. With virtualenv installed, creating a new project environment is easy. From your terminal shell:

~$ mkdir ~/project
~/$ cd project
~/project$ virtualenv env
~/project$ source env/bin/activate

From here you can use pip or to install the package and it will be restricted to the copy of python in the env directory. You can leave the virtual environment by typing deactivate in the terminal, and restart the environment with source env/bin/activate.


pip is the easiest way to install Chessnut. It can be installed directly from the pypi package:

pip install Chessnut

Upgrading to the latest version can be performed with the -U flag:

pip install -U Chessnut

Or from the github repository:

pip install git+

If you prefer, you can install Chessnut manually with After downloading the source files to a local directory (and setting up a virtualenv), switch into the project directory and run

python -m install

(Note: To install the package globally you may have to use the sudo command.)

As a Module

Finally, Chessnut is also a standalone module, so if you place the Chessnut directory within your project folder, you don’t need to install the package, you can just import the module as usual. (Using one of the package versions–particularly PIP–is still recommended as a way to create separation between your code and the Chessnut package, so that you don’t have to worry about merging your changes into future upgrades of Chessnut.

from Chessnut import Game


*<your code>*


Unit tests can be run with the shell script which launches the ` <>`__ framework as configured in .coveragerc, or you can use the standard unittest framework via python -m unittest discover. If you install the pylint package, you can run the checker with default options using pylint --ignore=tests Chessnut.

Using Chessnut

There are only two real classes in the Chessnut package: Board and Game. (There is also a namedtuple, State, which creates a class, and another class, InvalidMove–a subclass of Exception, used to avoid generic try/except statements). Board is only used internally by Game to keep track of pieces and perform string formatting to and from FEN notation, so Game should be the only class you need to import. After installing the Chessnut package, you can import and use it as you would expect:

from Chessnut import Game

chessgame = Game()
print(chessgame)  # 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'

['a2a3', 'a2a4', 'b2b3', 'b2b4', 'c2c3', 'c2c4', 'd2d3', 'd2d4', 'e2e3',
 'e2e4', 'f2f3', 'f2f4', 'g2g3', 'g2g4', 'h2h3', 'h2h4', 'b1c3', 'b1a3',
 'g1h3', 'g1f3']

chessgame.apply_move('e2e4')  # succeeds!
print(chessgame)  # 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1'

chessgame.apply_move('e2e4')  # fails! (raises InvalidMove exception)
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
Chessnut-0.3.1.tar.gz (11.3 kB) Copy SHA256 Checksum SHA256 Source Aug 14, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting