Create Your Own Variants • PyChess
By PyChess
Community
By gbtami
Create Your Own Variants
gbtami
2026-07-07<br>673 views<br>en
New variant moratorium is over. Forever.
*"Anyone can invent a new chess variant within ten seconds (try it) and unfortunately some people do."* D.B. Pritchard
We are happy to announce one of the biggest PyChess features so far: **user-defined variants**.
Until now, adding a new variant to PyChess required code changes, deployment work, new graphics, and a lot of coordination. With this update, signed-in users can create their own playable variants directly on the site by uploading a Fairy-Stockfish style rules definition. You can test the variant against the AI, invite other players, add a custom piece set or board, and finally publish it as a community variant when it is ready.
This does **not** mean that every possible chess-like game can be supported automatically. PyChess still needs to understand the board, moves, pieces, clocks, notation, game saving, spectators, and UI. But many variants that can be described with Fairy-Stockfish's `variants.ini` format can now be tested and shared without waiting for a full site release.
## Where to start
Go to **My variants** from TOOLS menu. There you can upload, check, edit, clone, archive, delete, test, and decorate your own variants.
The basic workflow is:
1. Write a Fairy-Stockfish `variants.ini` definition for your variant.<br>2. Paste it into the **Upload new variant** form.<br>3. Add a display name and description.<br>4. Start with **Private** visibility.<br>5. Use **Check rules** to validate the definition.<br>6. Upload the variant.<br>7. Test it against Fairy-Stockfish or with another player.<br>8. Refine the rules while it is still private.<br>9. Optionally upload custom SVG pieces and a custom SVG board.<br>10. Change the visibility to **Public** when the variant is ready for the community.
This private-first workflow is strongly recommended. Variant design usually needs playtesting. Sometimes the first version is too sharp, too drawish, unbalanced, or simply has a typo in the rules. Private variants are meant to be a safe sandbox for this.
## What is Fairy-Stockfish `variants.ini`?
PyChess uses [Fairy-Stockfish](https://github.com/fairy-stockfish/Fairy-Stockfish) for many chess variants. Fairy-Stockfish is a chess variant engine derived from Stockfish and designed to support many regional, historical, fairy, and custom variants.
Fairy-Stockfish custom variants are described with an INI-style configuration format, usually called `variants.ini`. A custom variant definition can describe things such as:
* the base or inherited variant,<br>* board size,<br>* piece types and their movements,<br>* starting position,<br>* castling rules,<br>* promotion rules,<br>* drops and pockets,<br>* checking and royal pieces,<br>* win/loss/draw conditions,<br>* special regions of the board.
You can read the Fairy-Stockfish custom variant documentation here:
[https://fairy-stockfish.github.io/custom-variants/](https://fairy-stockfish.github.io/custom-variants/)
The main Fairy-Stockfish `variants.ini` file is also very useful because it contains many real examples:
[https://github.com/fairy-stockfish/Fairy-Stockfish/blob/master/src/variants.ini](https://github.com/fairy-stockfish/Fairy-Stockfish/blob/master/src/variants.ini)
A very small definition can look like this:
```ini<br>[myvariant:chess]<br>## inherits chess rules through the section suffix<br>```
Real variants are usually more interesting than that, of course. They may define custom pieces, a different board size, special promotion rules, pockets, regions, or a completely different starting position.
The section name, such as `[myvariant:chess]`, is important. It becomes the internal variant key used by the site and by Fairy-Stockfish. Variant keys must be short, lowercase, and unique. If you change the rules while testing, it is usually best to also change the section name, because an already loaded runtime variant cannot always be safely replaced under the same key.
## Not every Fairy-Stockfish rule is supported
Fairy-Stockfish is very powerful, but PyChess also needs to display and save the game correctly in the browser. For that reason, uploaded variants go through additional PyChess validation.
The **Check rules** button tries to catch unsupported or unsafe definitions before the variant is saved. Some Fairy-Stockfish options need special UI support, special move input, special adjudication, or special multiplayer logic. Those options may be rejected even if Fairy-Stockfish itself understands them.
This is intentional. It is better to reject a rule clearly than to allow a variant that later breaks move input, game saving, analysis, clocks, spectators, or old game replays.
If your definition is rejected, read the error message carefully. Often the solution is to simplify the rule, use a closer existing template, or ask for help in the PyChess community.
Some Fairy-Stockfish rule names can also be confusing because...