What is Pikafish?
Pikafish is a free, open-source Xiangqi engine: a program that takes a position and returns the move it considers best, along with a numerical judgment of who stands better. It has no interface of its own. It is a calculation core that talks to a graphical program through text commands, the way an engine sits under the hood of a car. That design is deliberate: by separating the engine from the interface, the same core can power a desktop analysis board, a phone app, or a website. Pikafish has become the reference engine of the Xiangqi world for the same reasons Stockfish did in chess: it is stronger than the commercial alternatives, it costs nothing, and its source code is public so anyone can verify what it does. If you want the broader picture of how computers came to dominate Xiangqi, our overview of Xiangqi AI engines covers the full history; this article focuses on Pikafish itself.
Where does Pikafish come from? The Stockfish lineage
Pikafish is a derivative of Stockfish, the open-source chess engine that has dominated computer chess for over a decade. Rather than rebuilding a search algorithm from scratch, its authors took Stockfish's proven search — the part that decides which branches of the move tree are worth exploring and which can be safely pruned — and adapted it to a game with a 9x10 board, a river, a palace, and pieces that behave nothing like their chess counterparts. The evaluation had to be rebuilt entirely, because knowing that a chariot is powerful on an open file says nothing about how to value a cannon that needs a screen to capture. That inheritance explains a lot about Pikafish: the command language, the configuration options, the release conventions and the licence all come from the Stockfish family. It is distributed under the GPL v3, which means it is free to use and modify, but any derived work must also be published under the same terms.
How strong is Pikafish really?
Very strong — strong enough that the question of beating it no longer has a serious answer. On ordinary modern hardware, given a few seconds per move, Pikafish plays well beyond the level of the strongest human Grandmasters. It does not blunder, it never gets tired, it calculates forcing sequences deeper than any human can hold in their head, and it evaluates quiet positions with a consistency that no player sustains across a long game. The interesting comparison is not human versus engine but what the engine is useful for. A player rated 1400 gains nothing from being told a position is losing by two points; they gain from understanding which move created the problem. That is why raw engine strength matters far less than how you use it. Our article on Elo ratings in Xiangqi puts human rating scales in perspective, and shows why the gap between a club player and a Grandmaster is smaller than the gap between a Grandmaster and an engine.
What is NNUE, and why does Pikafish need a separate file?
NNUE stands for efficiently updatable neural network, and it is the part of Pikafish that judges positions. Classical engines evaluated a position with rules written by hand: a chariot is worth this much, a protected soldier past the river is worth that much, an exposed general is a penalty. NNUE replaces that handwritten table with a small neural network trained on millions of positions, which captures subtleties nobody managed to express as rules. The word efficiently is the key: the network is designed so that when a single piece moves, only a small part of the computation has to be redone, which is what makes it fast enough to run millions of times per second. Practically, this network lives in a separate file, usually named something like pikafish.nnue. The engine binary alone does not contain it. This is the single most common source of confusion for newcomers, and the subject of the next section.
How do you download and run Pikafish?
Pikafish is distributed as a compiled binary on its public repository, github.com/official-pikafish/Pikafish, with builds for Windows, Linux, macOS and Android. The releases usually offer several variants of the same version, named after processor instruction sets — avx2, bmi2, vnni and similar. These are not different engines; they are the same program compiled to exploit more or less recent processor features. Pick the most recent one your machine supports; if it refuses to start with an illegal instruction error, step down to a more conservative build. The release archive already contains the NNUE network, so a normal download needs no extra step. You only fetch the network yourself when you compile from source; it lives in the Networks repository and belongs next to the binary. The failure is not subtle either: an engine that cannot load its network prints the path it tried and the URL to download it from, then exits — it never plays on with weak moves. Finally, remember that the binary has no window and no board: you need a graphical interface that speaks the same protocol to actually use it.
How do you configure Pikafish properly?
Three settings account for nearly all of the practical difference. Threads tells the engine how many processor cores to use. More threads means more positions examined per second, but leaving at least one core free keeps your machine responsive; setting it above your actual core count only slows things down. Hash is the memory the engine uses to remember positions it has already evaluated, expressed in megabytes. Too little and it recalculates the same things endlessly; too much and it competes with the rest of your system. A few hundred megabytes is comfortable for analysis on a normal computer. The third setting is not really a setting: it is how long you let it think. Engine strength grows with time, but with diminishing returns — the jump from one second to ten is large, from ten seconds to a hundred much smaller. For studying your own games, a few seconds per position is plenty. The same trade-offs, applied to opponents rather than analysis, are what we describe in how we balance bot difficulty.
How do you read what Pikafish tells you?
The engine outputs a continuous stream of lines, and three numbers matter. The evaluation is expressed in pawn-equivalents from the side to move's point of view: a positive score means the side to move is better, and a score around zero means balance. A value like plus-one means roughly the advantage of a healthy extra soldier, not a won game. The depth is how many plies ahead it has searched; a high evaluation at low depth deserves much less trust than a modest one at high depth. The principal variation is the sequence of moves the engine considers best for both sides, and it is by far the most instructive part: the evaluation tells you that something is wrong, the variation tells you why. Beginners read only the number; players who improve read the line. If the notation in those lines is unfamiliar, our guide to Xiangqi notation explains the systems in use.
Using an engine to improve — and where the line is
An engine is a merciless answer machine, which makes it both the best and the worst study partner. The productive method is to analyse your own games after playing them, and to think before you look: form your own judgment about where the game turned, then check. When the engine disagrees with you, the disagreement is the lesson. The unproductive method is to click through a game watching the evaluation bar move, which feels like studying and teaches nothing. Below roughly 2000, most losses come from tactics you can find yourself with more discipline, not from subtleties an engine reveals — our Xiangqi improvement guide sets out a more effective progression. And the obvious point that still needs saying: using engine assistance during a live game against another person is cheating, on every serious platform and in every federation. Engines are for after the game, or for positions nobody is playing.
Using Pikafish without installing anything
If all you want is a strong engine analysing your positions, you do not have to install anything at all. Xiangqi One runs Pikafish directly, natively in the mobile apps and compiled to WebAssembly in the browser, so the analysis happens on your own device with no setup, no network file to download and no configuration. You can open a board, play through a game, and get the same engine judgment described above at whatever depth you have patience for. The bots you play against use the same core, deliberately restrained to produce opponents at a level that is actually useful to play — the reasoning behind that is in how we balance bot difficulty. To analyse a position or play against a calibrated opponent right now, open Xiangqi One. For the wider landscape of engines and how computers changed the game, continue with our overview of Xiangqi AI engines or browse the engines category.
