Skip to main content

Mahjong hands calculation

Project description

For now only Python 3.5+ is supported.

Riichi mahjong hands calculation

This library can calculate hand cost (han, fu with details, yaku and scores) for riichi mahjong (japanese version).

It supports features like:

  • Disable or enable aka dora in the hand
  • Disable or enable open tanyao yaku
  • Disable or enable double yakuman (like suuanko tanki)

The code was validated on phoenix replays in total on 11,120,125 hands.

So, we can say that our own hand calculator works the same way that hand calculation.

Right now it supports only japanese version (riichi mahjong). MCR (chinese version) is in plans.

Project repository:

How to install

pip install mahjong

How to use

You can find more examples here:

Let’s calculate how much will cost this hand:

Tanyao hand by ron

from mahjong.hand_calculating.hand import HandCalculator
from mahjong.tile import TilesConverter
from mahjong.hand_calculating.hand_config import HandConfig
from mahjong.meld import Meld

calculator = HandCalculator()

# we had to use all 14 tiles in that array
tiles = TilesConverter.string_to_136_array(man='22444', pin='333567', sou='444')
win_tile = TilesConverter.string_to_136_array(sou='4')[0]

result = calculator.estimate_hand_value(tiles, win_tile)

print(result.han, result.fu)
for fu_item in result.fu_details:


1 40
{'fu': 30, 'reason': 'base'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 2, 'reason': 'open_pon'}

How about tsumo?

result = calculator.estimate_hand_value(tiles, win_tile, config=HandConfig(is_tsumo=True))

print(result.han, result.fu)
print(result.cost['main'], result.cost['additional'])
for fu_item in result.fu_details:


4 40
4000 2000
[Menzen Tsumo, Tanyao, San Ankou]
{'fu': 20, 'reason': 'base'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 2, 'reason': 'tsumo'}

What if we add open set?

melds = [Meld(meld_type=Meld.PON, tiles=TilesConverter.string_to_136_array(man='444'))]

result = calculator.estimate_hand_value(tiles, win_tile, melds=melds, config=HandConfig(has_open_tanyao=True))

print(result.han, result.fu)
for fu_item in result.fu_details:


1 30
{'fu': 20, 'reason': 'base'}
{'fu': 4, 'reason': 'closed_pon'}
{'fu': 2, 'reason': 'open_pon'}
{'fu': 2, 'reason': 'open_pon'}

Shanten calculation

from mahjong.shanten import Shanten

shanten = Shanten()
tiles = TilesConverter.string_to_136_array(man='13569', pin='123459', sou='443')
result = shanten.calculate_shanten(tiles)


Releases History

1.1.0 (2017-10-07)

Breaking changes:

  • Interface of hand calculator was changed. New interface will allow to easy support different game rules

Additional fixes:

  • Refactor hand divider. Allow to pass melds objects instead of arrays
  • Add file with usage examples
  • Minor project refactoring

1.0.5 (2017-09-25)

  • Improve installation script

1.0.4 (2017-09-25)

Bug fixes:

  • Fix refactoring regressions with kan sets and dora calculations
  • Fix regression with sankantsusuukantsu and called chankan
  • Closed kan can’t be used in chuuren poutou
  • Fix yaku ids (some of them had incorrect numbers)


  • Allow to disable double yakuman (like suuanko tanki)
  • Remove float calculations from scores and fu
  • Add travis build status
  • Add usage examples to the readme

1.0.3 (2017-09-23)

Project details

Download files

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

Files for mahjong, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size mahjong-1.1.0.tar.gz (22.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page