Skip to main content

PokerKit is an open-source software library, written in pure Python, for simulating games, evaluating hands, and facilitating statistical analysis, developed by the Universal, Open, Free, and Transparent Computer Poker Research Group. PokerKit supports an extensive array of poker variants and it provides a flexible architecture for users to define their custom games. These facilities are exposed via an intuitive unified high-level programmatic API. The library can be used in a variety of use cases, from poker AI development, and tool creation, to online poker casino implementation. PokerKit’s reliability has been established through static type checking, extensive doctests, and unit tests, achieving 99% code coverage.

Features

  • Extensive poker game logic for major and minor poker variants.

  • High-speed hand evaluations.

  • Customizable game states and parameters.

  • Robust implementation with static type checking and extensive unit tests and doctests.

Installation

The PokerKit library requires Python Version 3.11 or above and can be installed using pip:

pip install pokerkit

Usages

Example usages of PokerKit is shown below.

Multi-Runout in an All-In Situation

Below shows the 4-runout hand between Phil Hellmuth and the Loose Cannon Ernest Wiggins.

Link: https://youtu.be/cnjJv7x0HMY?si=4l05Ez7lQVczt8DI&t=638

Note that the starting stacks for some players are set to be math.inf as they are not mentioned.

from math import inf

from pokerkit import Automation, Mode, NoLimitTexasHoldem

state = NoLimitTexasHoldem.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    False,  # Uniform antes?
    {-1: 600},  # Antes
    (200, 400, 800),  # Blinds or straddles
    400,  # Min-bet
    (inf, 116400, 86900, inf, 50000, inf),  # Starting stacks
    6,  # Number of players
    mode=Mode.CASH_GAME,
)

# Below are the pre-flop dealings and actions.

state.deal_hole('JsTh')  # Tony G
state.deal_hole('Ah9d')  # Hellmuth
state.deal_hole('KsKc')  # Wiggins
state.deal_hole('5c2h')  # Negreanu
state.deal_hole('6h5h')  # Brunson
state.deal_hole('6s3s')  # Laak

state.fold()  # Negreanu
state.complete_bet_or_raise_to(2800)  # Brunson
state.fold()  # Laak
state.check_or_call()  # Tony G
state.complete_bet_or_raise_to(12600)  # Hellmuth
state.check_or_call()  # Wiggins
state.check_or_call()  # Brunson
state.check_or_call()  # Tony G

# Below are the flop dealing and actions.

state.burn_card('??')
state.deal_board('9hTs9s')

state.check_or_call()  # Tony G
state.complete_bet_or_raise_to(17000)  # Hellmuth
state.complete_bet_or_raise_to(36000)  # Wiggins
state.fold()  # Brunson
state.fold()  # Tony G
state.complete_bet_or_raise_to(103800)  # Hellmuth
state.check_or_call()  # Wiggins

# Below is selecting the number of runouts.

state.select_runout_count(4)  # Hellmuth
state.select_runout_count(None)  # Wiggins

# Below is the first runout.

state.burn_card('??')
state.deal_board('Jh')  # Turn
state.burn_card('??')
state.deal_board('Ad')  # River

# Below is the second runout.

state.burn_card('??')
state.deal_board('Kh')  # Turn
state.burn_card('??')
state.deal_board('3c')  # River

# Below is the third runout.

state.burn_card('??')
state.deal_board('7s')  # Turn
state.burn_card('??')
state.deal_board('8s')  # River

# Below is the fourth runout.

state.burn_card('??')
state.deal_board('Qc')  # Turn
state.burn_card('??')
state.deal_board('Kd')  # River

# Below are the final stacks.

print(state.stacks)  # [inf, 79400, 149700, inf, 37400, inf]

A Sample No-Limit Texas Hold’em Hand

Below shows the first televised million-dollar pot between Tom Dwan and Phil Ivey.

Link: https://youtu.be/GnxFohpljqM

Note that the starting stack of Patrik Antonius is set to be math.inf as it is not mentioned.

from math import inf

from pokerkit import Automation, NoLimitTexasHoldem

state = NoLimitTexasHoldem.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    True,  # Uniform antes?
    500,  # Antes
    (1000, 2000),  # Blinds or straddles
    2000,  # Min-bet
    (1125600, inf, 553500),  # Starting stacks
    3,  # Number of players
)

# Below are the pre-flop dealings and actions.

state.deal_hole('Ac2d')  # Ivey
state.deal_hole('????')  # Antonius
state.deal_hole('7h6h')  # Dwan

state.complete_bet_or_raise_to(7000)  # Dwan
state.complete_bet_or_raise_to(23000)  # Ivey
state.fold()  # Antonius
state.check_or_call()  # Dwan

# Below are the flop dealing and actions.

state.burn_card('??')
state.deal_board('Jc3d5c')

state.complete_bet_or_raise_to(35000)  # Ivey
state.check_or_call()  # Dwan

# Below are the turn dealing and actions.

state.burn_card('??')
state.deal_board('4h')

state.complete_bet_or_raise_to(90000)  # Ivey
state.complete_bet_or_raise_to(232600)  # Dwan
state.complete_bet_or_raise_to(1067100)  # Ivey
state.check_or_call()  # Dwan

# Below is the river dealing.

state.burn_card('??')
state.deal_board('Jh')

# Below are the final stacks.

print(state.stacks)  # [572100, inf, 1109500]

A Sample Short-Deck Hold’em Hand

Below shows an all-in hand between Xuan and Phua.

Link: https://youtu.be/QlgCcphLjaQ

from pokerkit import Automation, NoLimitShortDeckHoldem

state = NoLimitShortDeckHoldem.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    True,  # Uniform antes?
    3000,  # Antes
    {-1: 3000},  # Blinds or straddles
    3000,  # Min-bet
    (495000, 232000, 362000, 403000, 301000, 204000),  # Starting stacks
    6,  # Number of players
)

# Below are the pre-flop dealings and actions.

state.deal_hole('Th8h')  # Badziakouski
state.deal_hole('QsJd')  # Zhong
state.deal_hole('QhQd')  # Xuan
state.deal_hole('8d7c')  # Jun
state.deal_hole('KhKs')  # Phua
state.deal_hole('8c7h')  # Koon

state.check_or_call()  # Badziakouski
state.check_or_call()  # Zhong
state.complete_bet_or_raise_to(35000)  # Xuan
state.fold()  # Jun
state.complete_bet_or_raise_to(298000)  # Phua
state.fold()  # Koon
state.fold()  # Badziakouski
state.fold()  # Zhong
state.check_or_call()  # Xuan

# Below is the flop dealing.

state.burn_card('??')
state.deal_board('9h6cKc')

# Below is the turn dealing.

state.burn_card('??')
state.deal_board('Jh')

# Below is the river dealing.

state.burn_card('??')
state.deal_board('Ts')

# Below are the final stacks.

print(state.stacks)  # [489000, 226000, 684000, 400000, 0, 198000]

A Sample Pot-Limit Omaha Hold’em Hand

Below shows the largest online poker pot ever played between Patrik Antonius and Viktor Blom.

Link: https://youtu.be/UMBm66Id2AA

from pokerkit import Automation, PotLimitOmahaHoldem

state = PotLimitOmahaHoldem.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    True,  # Uniform antes?
    0,  # Antes
    (500, 1000),  # Blinds or straddles
    1000,  # Min-bet
    (1259450.25, 678473.5),  # Starting stacks
    2,  # Number of players
)

# Below are the pre-flop dealings and actions.

state.deal_hole('Ah3sKsKh')  # Antonius
state.deal_hole('6d9s7d8h')  # Blom

state.complete_bet_or_raise_to(3000)  # Blom
state.complete_bet_or_raise_to(9000)  # Antonius
state.complete_bet_or_raise_to(27000)  # Blom
state.complete_bet_or_raise_to(81000)  # Antonius
state.check_or_call()  # Blom

# Below are the flop dealing and actions.

state.burn_card('??')
state.deal_board('4s5c2h')

state.complete_bet_or_raise_to(91000)  # Antonius
state.complete_bet_or_raise_to(435000)  # Blom
state.complete_bet_or_raise_to(779000)  # Antonius
state.check_or_call()  # Blom

# Below is the turn dealing.

state.burn_card('??')
state.deal_board('5h')

# Below is the river dealing.

state.burn_card('??')
state.deal_board('9c')

# Below are the final stacks.

print(state.stacks)  # [1937923.75, 0.0]

A Sample Fixed-Limit Deuce-To-Seven Lowball Triple Draw Hand

Below shows a bad beat between Yockey and Arieh.

Link: https://youtu.be/pChCqb2FNxY

from pokerkit import Automation, FixedLimitDeuceToSevenLowballTripleDraw

state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    True,  # Uniform antes?
    0,  # Antes
    (75000, 150000),  # Blinds or straddles
    150000,  # Small-bet
    300000,  # Big-bet
    (1180000, 4340000, 5910000, 10765000),  # Starting stacks
    4,  # Number of players
)

# Below are the pre-flop dealings and actions.

state.deal_hole('7h6c4c3d2c')  # Yockey
state.deal_hole('??????????')  # Hui
state.deal_hole('??????????')  # Esposito
state.deal_hole('AsQs6s5c3c')  # Arieh

state.fold()  # Esposito
state.complete_bet_or_raise_to()  # Arieh
state.complete_bet_or_raise_to()  # Yockey
state.fold()  # Hui
state.check_or_call()  # Arieh

# Below are the first draw and actions.

state.stand_pat_or_discard()  # Yockey
state.stand_pat_or_discard('AsQs')  # Arieh
state.burn_card('??')
state.deal_hole('2hQh')  # Arieh

state.complete_bet_or_raise_to()  # Yockey
state.check_or_call()  # Arieh

# Below are the second draw and actions.

state.stand_pat_or_discard()  # Yockey
state.stand_pat_or_discard('Qh')  # Arieh
state.burn_card('??')
state.deal_hole('4d')  # Arieh

state.complete_bet_or_raise_to()  # Yockey
state.check_or_call()  # Arieh

# Below are the third draw and actions.

state.stand_pat_or_discard()  # Yockey
state.stand_pat_or_discard('6s')  # Arieh
state.burn_card('??')
state.deal_hole('7c')  # Arieh

state.complete_bet_or_raise_to()  # Yockey
state.check_or_call()  # Arieh

# Below are the final stacks.

print(state.stacks)  # [0, 4190000, 5910000, 12095000]

A Sample Badugi Hand

Below shows an example badugi hand from Wikipedia.

Link: https://en.wikipedia.org/wiki/Badugi

Note that the starting stacks are set to be math.inf as they are not mentioned.

from math import inf

from pokerkit import Automation, FixedLimitBadugi

state = FixedLimitBadugi.create_state(
    # Automations
    (
        Automation.ANTE_POSTING,
        Automation.BET_COLLECTION,
        Automation.BLIND_OR_STRADDLE_POSTING,
        Automation.HAND_KILLING,
        Automation.CHIPS_PUSHING,
        Automation.CHIPS_PULLING,
    ),
    True,  # Uniform antes?
    0,  # Antes
    (1, 2),  # Blinds or straddles
    2,  # Small-bet
    4,  # Big-bet
    inf,  # Starting stacks
    4,  # Number of players
)

# Below are the pre-flop dealings and actions.

state.deal_hole('????????')  # Bob
state.deal_hole('????????')  # Carol
state.deal_hole('????????')  # Ted
state.deal_hole('????????')  # Alice

state.fold()  # Ted
state.check_or_call()  # Alice
state.check_or_call()  # Bob
state.check_or_call()  # Carol

# Below are the first draw and actions.

state.stand_pat_or_discard('????')  # Bob
state.stand_pat_or_discard('????')  # Carol
state.stand_pat_or_discard('??')  # Alice
state.burn_card('??')
state.deal_hole('????')  # Bob
state.deal_hole('????')  # Carol
state.deal_hole('??')  # Alice

state.check_or_call()  # Bob
state.complete_bet_or_raise_to()  # Carol
state.check_or_call()  # Alice
state.check_or_call()  # Bob

# Below are the second draw and actions.

state.stand_pat_or_discard('??')  # Bob
state.stand_pat_or_discard()  # Carol
state.stand_pat_or_discard('??')  # Alice
state.burn_card('??')
state.deal_hole('??')  # Bob
state.deal_hole('??')  # Alice

state.check_or_call()  # Bob
state.complete_bet_or_raise_to()  # Carol
state.complete_bet_or_raise_to()  # Alice
state.fold()  # Bob
state.check_or_call()  # Carol

# Below are the third draw and actions.

state.stand_pat_or_discard('??')  # Carol
state.stand_pat_or_discard()  # Alice
state.burn_card('??')
state.deal_hole('??')  # Carol

state.check_or_call()  # Carol
state.complete_bet_or_raise_to()  # Alice
state.check_or_call()  # Carol

# Below is the showdown.

state.show_or_muck_hole_cards('2s4c6d9h')  # Alice
state.show_or_muck_hole_cards('3s5d7c8h')  # Carol

# Below are the final stacks.

print(state.stacks)  # [inf, inf, inf, inf]
print(state.payoffs)  # [-4, 20, 0, -16]

Testing and Validation

PokerKit has extensive test coverage, passes mypy static type checking with strict mode, and has been validated through extensive use in real-life scenarios.

Contributing

Contributions are welcome! Please read our Contributing Guide for more information.

License

PokerKit is distributed under the MIT license.

Citing

If you use PokerKit in your research, please cite our library:

@ARTICLE{10287546,
  author={Kim, Juho},
  journal={IEEE Transactions on Games},
  title={PokerKit: A Comprehensive Python Library for Fine-Grained Multivariant Poker Game Simulations},
  year={2025},
  volume={17},
  number={1},
  pages={32-39},
  keywords={Games;Libraries;Automation;Artificial intelligence;Python;Computational modeling;Engines;Board games;card games;game design;games of chance;multiagent systems;Poker;rule-based systems;scripting;strategy games},
  doi={10.1109/TG.2023.3325637}}

Download files

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

Source Distribution

pokerkit-0.7.5.tar.gz (109.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pokerkit-0.7.5-py3-none-any.whl (113.9 kB view details)

Uploaded Python 3

File details

Details for the file pokerkit-0.7.5.tar.gz.

File metadata

  • Download URL: pokerkit-0.7.5.tar.gz
  • Upload date:
  • Size: 109.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.3

File hashes

Hashes for pokerkit-0.7.5.tar.gz
Algorithm Hash digest
SHA256 7eed51e55821295d9ccaf83dbdc61f6905b8a6f4829da115513ea148e86e8102
MD5 f11be46628098256d37e60048d7bc7da
BLAKE2b-256 c0a88a40e4d0fcf92b178e2c2cb6a959ed4ef8e23e9f11e011e0389e15f794f8

See more details on using hashes here.

File details

Details for the file pokerkit-0.7.5-py3-none-any.whl.

File metadata

  • Download URL: pokerkit-0.7.5-py3-none-any.whl
  • Upload date:
  • Size: 113.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.3

File hashes

Hashes for pokerkit-0.7.5-py3-none-any.whl
Algorithm Hash digest
SHA256 3e1a0b2a8a9785369c86e2c1392dd2204ee536fbcbe77a779c875bd545eb63e8
MD5 d2343bd2e43dd770d1043d76f16c7b18
BLAKE2b-256 3f15e2c2c1acf4a2e17fc9c300564befe758cc0a97067a7e841cff579681c316

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.7.5 This release

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.17

2 files

0.4.16

2 files

0.4.15

2 files

0.4.14

2 files

0.4.13

2 files

0.4.12

2 files

0.4.11

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

0.0.2

2 files

0.0.1

2 files

0.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page