Poker Hand Evaluator Software: How Winning Hands Are Ranked in Code

Palak Bhalgami Palak Bhalgami
Published
15 mins read
Poker Hand Evaluator Software: How Winning Hands Are Ranked in Code

Poker hand evaluator software takes a player’s hole cards and the board and returns one number for the strongest five-card hand available, so any two hands can be compared with a plain integer comparison. The ranking logic is a mapping from card combinations to a sortable score. The hard part is doing that mapping fast and correctly for every edge case. This article walks through the scale, the seven-card problem, lookup tables and the libraries that implement them.

On this page

Poker Hand Evaluator Software: What It Does with Each Hand

An evaluator answers one question: how strong is this hand? It does not deal cards, shuffle a deck, manage betting or decide who acts next. It receives cards, applies the ranking rules and returns a value. Everything else in a poker engine, from showdown resolution to pot splitting to equity calculators, depends on that value being right.

The inputs depend on the variant. In Texas hold’em a player has two hole cards and the board eventually holds five community cards, so a showdown evaluates seven cards and picks the best five. Earlier streets give you five or six cards, which is why most libraries accept more than one input size. Five-card draw and stud variants feed in different counts again. Omaha adds a constraint, because the player must use exactly two hole cards and three board cards, so the engine has to generate legal combinations before it scores anything.

The output is the part that shapes your architecture. A naive evaluator returns a named category such as “full house” or “two pair”. That is readable but useless for comparison on its own. Two full houses are both “full house”, yet kings full of aces beats nines full of eights. To settle a showdown you would need a second function to compare ranks within the category, then a third to compare kickers. Every comparison turns into a branching tree of special cases.

A single sortable value removes that tree. If every distinct five-card hand strength maps to one integer, then the showdown is min(scores) or max(scores) depending on the convention. Ties fall out naturally, because equal hands produce equal integers. Sorting a list of players by hand strength becomes a one-line operation. Equity simulations, which evaluate hands millions of times, benefit most, since each comparison costs one integer check.

The reference order for categories comes from the standard poker hand rankings, from straight flush at the top down through four of a kind, full house, flush, straight, three of a kind, two pair, one pair and high card. Any evaluator you build or adopt has to reproduce that order exactly, with the usual rules that suits never break ties and that the ace plays high or low in a straight.

This is separate from the randomness side of a poker product. The evaluator is deterministic: the same cards always return the same score. Shuffling is a different component with different audit requirements, covered in our pieces on hardware vs software RNG. If you are mapping the wider system around the evaluator, our guide to online poker game development shows where hand ranking sits next to game state, networking and anti-cheat.

How Hand Categories Map onto One Numeric Scale

The scale is a single integer where one end is the best possible hand and the other end is the worst. Which end is which is a convention, and it is the first thing to verify in any library you adopt.

“[ 6 ] [ 7 ] Suits are not ranked, so hands that differ by suit alone are of equal rank.”

— Wikipedia

Cactus Kev’s scale is the best-known example. It assigns 1 to a royal straight flush and 7462 to the weakest hand, seven-high with no pair (7-5-4-3-2, unsuited). The number 7462 is not arbitrary. It is the count of distinct hand strengths in five-card poker once you collapse suits, because a flush in hearts and a flush in spades with identical ranks tie. There are 2,598,960 five-card combinations, but only 7,462 meaningfully different strengths.

The PH Evaluator Python package documents the same 1 to 7462 range, and the @pokertools/evaluator npm package follows the same idea of lower scores for stronger hands. If you have used one of them, the other will feel familiar.

Score Bands per Category

Each category occupies a contiguous band of the scale. Within Cactus Kev’s numbering, the bands run as follows.

Category Distinct strengths Score range
Straight flush (including royal) 10 1 to 10
Four of a kind 156 11 to 166
Full house 156 167 to 322
Flush 1,277 323 to 1599
Straight 10 1600 to 1609
Three of a kind 858 1610 to 2467
Two pair 858 2468 to 3325
One pair 2,860 3326 to 6185
High card 1,277 6186 to 7462

The counts explain the shape. Only ten straights exist by rank, from A-2-3-4-5 up to 10-J-Q-K-A, so the straight band is tiny. One pair has 2,860 strengths because the pair rank and three kickers vary independently. The bands are ordered by rarity, with the exception that a flush ranks above a straight even though the counts suggest otherwise at the margin. The ranking follows the rules of the game, not the counts.

Kickers Inside a Band

Within a band, the score is determined by the ranks that matter, in order of importance. For four of a kind, the quad rank comes first and the single kicker second. Four aces with a king sits at the top of the band, at 11. Four twos with a three sits at the bottom, at 166. For a pair, the pair rank dominates, then the three kickers are compared from high to low. Two hands with the same pair and the same three kickers tie and get the same integer, whatever their suits.

The wheel deserves a specific note. A-2-3-4-5 is the lowest straight, with the ace playing low, so it takes the last slot in the straight band. The same applies to a steel wheel, the lowest straight flush. If your tests do not cover the wheel, they will miss the most common implementation bug in this area.

Check the Direction Before You Sort

Libraries differ on direction. Some return lower scores for stronger hands, as in the Cactus Kev lineage. Others return higher scores for stronger hands, which is the more intuitive reading of the word “score”. Mixing the two inside one codebase is a quiet way to award pots to the wrong player. Read the documented convention, write it into your own wrapper’s name and comments, and add a test that asserts a royal flush beats a pair under whichever direction you chose.

Why Seven-Card Evaluation Reduces to Five-Card Lookups

A seven-card hand is evaluated by scoring its best five-card subset, which means checking 21 combinations. Seven choose five is 21, and the best hand a player can make is the strongest of those 21 five-card hands. Every classical seven-card evaluator starts from this fact, even the ones that later avoid doing the work.

The Brute-Force Method

The straightforward implementation takes a five-card evaluator and runs it across every subset. You generate the 21 index combinations once, loop through them for each hand, score each five-card subset and keep the best result. Under the Cactus Kev convention you keep the minimum. It is simple to write and simple to verify, because the five-card function is the only piece with ranking logic in it.

The cost is the multiplier. One showdown now means 21 evaluations plus the overhead of building each subset. For a single hand dealt to a human player, nobody notices. For a server settling thousands of tables, or an equity calculator simulating boards at scale, the multiplier dominates the profile. That is why the approach is now described as too slow for high-volume play, and why perfect-hash lookups have largely replaced it in production engines. The next section covers those.

How Treys Handles 6- and 7-card Hands

The Treys pure-Python library is a clear example of the subset approach in practice. It handles 5-, 6- and 7-card lookups, and for the 6- and 7-card cases it works combinatorially, evaluating the 5-card choices and combining the results. The 6-card case checks six subsets. The 7-card case checks the full 21.

Being pure Python is a design choice with a price. Interpreted code will not match compiled implementations on throughput, which makes Treys a poor fit when you need to evaluate at scale. It makes Treys a good fit for several other jobs.

  • Prototyping: You can get a working showdown in an afternoon and see the full ranking flow without compiling anything.
  • Reference testing: A slow, readable implementation is a useful oracle. Run the same hands through a fast library and through Treys, then diff the scores.
  • Tooling and analysis: Offline scripts, hand-history review and one-off simulations rarely need peak throughput.
  • Teaching the team: Engineers new to poker logic can read the code and follow the ranking step by step.

The reference-testing role is the one to keep in mind. When you adopt a faster evaluator, its table-driven internals are hard to inspect by eye. A subset-scanning implementation is easy to reason about, so disagreement between the two points you directly at a bug.

There is also a middle ground for variants. Omaha forces exactly two hole cards and three board cards, which in four-card Omaha gives 6 hole pairs times 10 board triples, or 60 candidate hands. Five-card Omaha raises that to 100 and six-card Omaha to 150. Brute force scales badly here, and that scaling is part of why table-based designs matter, as the next section shows.

Perfect Hash and Lookup Tables for Constant-Time Ranking

Modern evaluators replace subset scanning with precomputed perfect hash and lookup tables that return a hand’s strength in one step. Instead of computing a rank by sorting cards and testing for pairs, straights and flushes, the evaluator converts the hand into a key, and the key indexes straight into a table that already holds the answer.

What the Perfect Hash Does

A hash function maps inputs to table slots, and collisions occur when two different inputs land in the same slot. A perfect hash is built so that no collisions occur for the known set of inputs. In poker the input set is finite and fully enumerable: every possible combination of ranks, with a separate path for flushes. You build the table offline, once, by scoring every combination with a reference evaluator. At runtime the hash turns the cards into an index and one read returns the score. No loops over subsets and no sorting are involved, so the time per hand does not grow with the hand’s complexity. That is what constant time, or O(1), means here.

The @pokertools/evaluator npm package describes its approach in these terms. Its page says it uses perfect hash tables and lookup tables for O(1) hand evaluation, and it returns lower scores for stronger hands. As of early October 2026 the package lists version 2.1.0 as latest, published about a month earlier. Treat the version as a snapshot. Check the registry again before you pin a dependency.

The Trade-Off Is Table Size

Precomputation moves the cost from time to memory and storage. A five-card table is modest because the distinct-strength space is only 7,462 values. Seven-card tables are larger because they cover more input combinations, and the table sizes you accept depend on the platform. A server process with gigabytes of RAM shrugs at tables that would hurt a mobile client or a browser bundle.

The PH Evaluator Python package shows the trade-off clearly in its Omaha support. Its README makes PLO5 and PLO6 evaluation opt-in, because the lookup tables are very large, hundreds of MB of generated C source each. The authors could have shipped those tables by default. They chose not to, because every user would pay the build time and size cost, including the many who only deal hold’em.

The lesson for variant planning is that the ranking logic barely changes. The category order is the same. The five-card strength scale is the same. What grows is the number of input combinations the table has to cover. Adding a variant to a table-driven evaluator is usually a storage and build problem, not a rules problem, so budget for table size, generation time and load time before you promise a game type to a product owner.

Some practical consequences follow.

  • Build step: Generated tables mean a build or install step, sometimes with a compiler. Include it in your CI and your container images.
  • Startup cost: Large tables take time to load into memory. Load once per process, not per request.
  • Distribution: A client-side evaluator for the browser has a tighter size budget than a server-side one, so decide where evaluation runs.
  • Variant gating: Make large-variant tables optional in your own packaging, the way the PH Evaluator does, so hold’em-only deployments stay lean.

Authoritative evaluation should always happen on the server. A client may compute a score for display, but the showdown result must come from code the player cannot alter.

Choosing and Testing a Poker Hand Evaluator Library

Choose an evaluator by checking its scale convention, supported variants, runtime requirements and release status before benchmarking. Speed matters, but a fast library with the wrong direction, an unsupported variant or an abandoned repository costs more than it saves.

Compare the Candidates on Facts, Not Claims

Several libraries illustrate the range of choices, and each has details worth noting.

  • PH Evaluator: Requires Python 3.10 or newer, returns ranks from 1 (royal flush) to 7462 (weakest) and keeps PLO5 and PLO6 opt-in because of table size.
  • pkrbot 1.1.0: A C++ package on PyPI, listed in December 2025, with an eval7-compatible API. It describes itself as a drop-in replacement for eval7 and 2-3x faster. Treat the speed claim as the maintainers’ own and measure it on your hardware.
  • pokereval (2011): A pure-Python package dated January 27, 2011. Its own description says it is nowhere near as fast as the C-based pypoker-eval but works if you cannot use C. It is a fallback, not a starting point.
  • Treys: Pure Python, readable and handy for tests, as covered earlier.

A runtime requirement such as Python 3.10 or newer can rule a library in or out before you read a line of code, if your servers run an older interpreter. Check it first.

Check Release Health

Evaluators are small, stable pieces of logic, so a quiet repository is not automatically a bad sign. Hand ranking rules do not change. But you still want evidence that the package you install is the package the maintainers published.

For eval7, PyPI shows a release signed through GitHub Actions and verified by PyPI on July 29, 2026. That is useful provenance, because it ties the artifact to a build in the source repository. Note that eval7’s README still says it is tested on Python 3.5 through 3.8. That text is old, so do not read it as the current support range. Test against your own interpreter.

The npm side shows the opposite pattern. A page capture from August 2025 showed the poker-evaluator package at version 2.1.1, published roughly a year earlier. That is not disqualifying for a small, finished library, but it should prompt you to read open issues, check whether the code runs on your Node version and decide who owns the fork if it breaks. Compare release dates against the registry, not against a README badge.

Evaluation code also sits close to compliance questions. Hand ranking is deterministic and easy to test, while the shuffle is where certification attention goes. If you are scoping that side, see our guide to RNG certification for gaming compliance, and keep the two components separate in your documentation.

A Test Plan That Catches Real Bugs

Before benchmarking, run a fixed set of cases against expected scores. Write the expected values by hand from the convention you chose, not by copying library output.

  1. Royal flush: A-K-Q-J-10 of one suit should return the best score on the scale, which is 1 under the Cactus Kev convention.
  2. Wheel straight: A-2-3-4-5 across mixed suits should be recognized as a straight, and it should rank below 2-3-4-5-6. Add the steel wheel for the straight flush case.
  3. Tied boards: Two players who both play the board, or who hold different suits with identical ranks, must receive equal scores. Check that your showdown code splits the pot rather than picking a winner by card order.
  4. Seven-card kicker case: Give two players the same pair from the board plus different hole cards, so the winner is decided by the fifth card. Add a case where the best five cards ignore one or both hole cards.
  5. Direction assertion: Assert that a pair loses to two pair using your wrapper’s comparison, so a future library swap that flips direction fails loudly.

Then run a cross-check. Generate a large batch of random hands, score them with your chosen library and with a slower reference such as Treys, and require identical ordering. Only after correctness is settled should you benchmark throughput on the hardware you will deploy.

If you would rather not own that integration yourself, our poker game development services cover the game logic layer, including hand evaluation, alongside the rest of the platform.

Poker Hand Evaluator Software FAQs Developers Ask Most

Should a poker hand evaluator return the same score for two tied hands?

Yes. Two hands in the same category with identical kickers should produce the same numeric score, because the evaluator’s job is to rank strength, not to pick a winner. Deciding who receives the pot when scores match is a separate step in the game logic that splits the pot among tied players.

Is a poker hand evaluator the same thing as a random number generator?

No. An evaluator only ranks cards that have already been dealt, while a random number generator produces the shuffle or deal in the first place. Each has its own compliance requirements, so a platform that certifies its shuffle should not assume the evaluator is covered by that certification.

Is the Treys library fast enough for a live multiplayer poker server?

Treys is pure Python and evaluates 5-, 6- and 7-card hands by combining 5-card results, which is convenient for tests, simulations and prototypes. A live server handling many tables should benchmark it against compiled or lookup-table evaluators before committing to it.

How do I check whether a poker evaluator package is still maintained?

Look at the last-published date on the package registry and confirm whether a newer version has appeared since the documentation was written. Signed releases with provenance, such as the eval7 release verified by PyPI in July 2026, give extra assurance that the code you install matches the source repository.

Palak Bhalgami

Palak Bhalgami

Palak Bhalgami brings 6+ years of expertise in iOS application development and 4 years of experience in Project Management, with a strong foundation in agile delivery as a Certified Scrum Master. At Source Code Lab, he provides strategic leadership and technical oversight for the delivery of enterprise-grade iGaming platforms, ensuring operational excellence, scalability, and adherence to business objectives.

Location Map

Let's Build Success

From concept to launch, we help build winning gaming platforms. Let's discuss your project.

Blog Form