Skip to main content

A Python package designed to play, develop strategies/algorithms, and implement the classic MasterMind board game.

Project description



A Python package designed to play, develop strategies/algorithms, and implement the classic MasterMind board game. It even includes a functioning, text-based implementation of MasterMind!


The source code for pymastermind is hosted on GitHub. You can install matermind through PyPI, with pip:

pip install pymastermind


pymastermind requires the following libraries:

  • pandas, used by the SelfGame object
  • tqdm, used to display progress bars when finding next guess. Note: only some algorithms support progress bars. See "Algorithms" below.


Read the full documentation for pymastermind here.

Example Usage


Play a game against your computer, or have your computer play itself, by running main() and following text-based instructions.

>>> main() # initiate the game; print instructions & wait for inputs


Several useful classes are defined in the pymastermind module.


Code objects are list instances designed to store a MasterMind codes. You can compare two codes by using the .compare() method. What's comparing?

>>> secret_code = Code(['a', 'b', 'c', 'd'])
>>> guess = Code(['b', 'c', 'j', 'd'])
>>> len(secret_code) == len(guess)
(1, 2)

Note: code objects must be of the same length to comapre.


Game objects are used to immitate gameplay.

>>> my_game = Game() # default: slots == 4, colors == ['a', 'b', 'c', 'd', 'e', 'f']
>>> secret_code = Code(['e', 'a', 'f', 'f'])
>>> my_game.guess # always the same for given setup; see Wikipedia article
['a', 'a', 'b', 'b']
>>> blacks_and_whites =
>>> blacks_and_whites
(1, 0)
>>> my_game.new_guess(response, algorithm='minmax') # new guess using minmax algorithm (see below)
>>> my_game.guess
['a', 'c', 'c', 'd']
>>> my_game.back() # go back one turn
>>> my_game.guess
['a', 'a', 'b', 'b']

Read the documentation for an in-depth look at all the attributes and methods of a Game.


A new guess can be generated using several different algorithms. Currently, pymastermind has two algorithms implemented:

  • random (default algorithm)
    • Set the guess to a random secret code possibility
    • No progress bar support yet
  • minmax
    • Set the guess to the guess that has the highest min-max score of all guesses. Read more here.
    • Supports progress bars

See the full documentation for a more detailed description of the algorithms.


SelfGame is a subclass of Game that is used to "play" games with specified algorithms and obtain a pandas DataFrame full of information about the games played.

>>> my_self_game = SelfGame() # same defaults, so slots == 4, colors == ['a', 'b', 'c', 'd', 'e', 'f']
>>> df = # default: games == 10, algorithm == 'random'
>>> type(df)
<class 'pandas.core.frame.DataFrame'>
>>> df.loc['Game 3', 'Turn 2'] # example query
Time                   0 days 00:00:00.000610
Start Possibilities                        23
End Possibilities                           4
Name: Game 3, dtype: object



Project details

Download files

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

Source Distribution

pymastermind-1.2.tar.gz (10.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page