Beginner Project

Learn How to Build a Matchmaker Game in Python: Absolute Beginners Tutorial

25 min read

A matchmaker game is one of the best first Python projects you can build. It is short enough to finish in a single session, it uses real Python concepts — lists, dictionaries, the random module, input(), functions, and loops — and it actually does something fun when it runs. By the end of this tutorial you will have a working command-line program that asks for a player's name and randomly assigns a compatibility match and score.

Python is a beginner-friendly language because the gap between writing code and seeing it do something is very small. A matchmaker game sits right in that sweet spot. You do not need a framework, a database, or a web server. You need a file, a terminal, and about 40 lines of code. That makes it an ideal vehicle for practicing the fundamentals before moving on to larger projects.

What the Game Does

When the player runs the program, it asks for their name. The program then selects a random match from a predefined list and displays the match name along with a compatibility score. The player can choose to play again or exit. Each run produces a different result because the selection is random.

The final version of the program will look like this when run:

output 
Welcome to Matchmaker!
Enter your name: Alex
Finding your match, Alex...

Your match is: Jordan
Compatibility score: 87%

Play again? (yes/no): no
Thanks for playing!
Note

This tutorial assumes Python 3.8 or later. To check your version, run python --version or python3 --version in your terminal.

Core Python Concepts You Will Use

Before writing any code it helps to understand what each piece is doing. The table below shows the concept, what it does in this project, and a simple example. Click any row to expand it.

Role in this project
A list holds all possible matches. Each match is a dictionary containing a name key and a score key. This structure lets you add as many matches as you like without changing any other code.
Example
matches = [{"name": "Jordan", "score": 87}, {"name": "Riley", "score": 72}]
Role in this project
Randomly selects one dictionary from the matches list. This is what makes the game different each time it runs. You need import random at the top of the file before calling it.
Example
result = random.choice(matches) — returns something like {"name": "Jordan", "score": 87}
Role in this project
Collects the player's name from the keyboard. Chaining .strip() removes accidental leading or trailing spaces, which prevents confusing output like " Alex" instead of "Alex".
Example
name = input("Enter your name: ").strip()
Role in this project
The matching logic lives in a get_match() function and the game loop lives in a main() function. Separating concerns like this keeps the code readable and makes each piece easier to change later.
Example
def get_match(player_name): ... — accepts a name string and returns the randomly chosen match dictionary.
Role in this project
Keeps the game running so the player can generate multiple matches without restarting the program. After each round, the loop checks the player's response and uses break to exit if they type anything other than yes.
Example
while True: ... if again != "yes": break
Pro Tip

Keep all your match data in one list at the top of the file. When you want to add or remove matches later, you only need to change that one list rather than hunting through logic scattered across multiple functions.

code builder click a token to place it

Build the correct line to randomly select one match from the matches list:

your code will appear here...
( matches random.shuffle random.choice result ) matches[0] =
Why: random.choice(matches) picks one item at random from the list. random.shuffle reorders the entire list in place and returns None, so assigning it to result would give you None, not a match. matches[0] always returns the first item, which is not random.

Writing the Code Step by Step

Create a new file called matchmaker.py. The sections below build the program one piece at a time, with an explanation of each part before you type it.

Step 1 — Import and data

The first line imports the random module from the Python standard library. Without this import, calling random.choice() later will raise a NameError. Below the import, define the matches list. Each element is a dictionary with two keys: name and score.

python 
import random

matches = [
    {"name": "Jordan",  "score": 87},
    {"name": "Riley",   "score": 72},
    {"name": "Morgan",  "score": 95},
    {"name": "Avery",   "score": 63},
    {"name": "Quinn",   "score": 81},
    {"name": "Taylor",  "score": 78},
    {"name": "Cameron", "score": 90},
]

Notice that the scores are hardcoded integers. This is intentional for a first version. In a more advanced version you could generate them randomly or calculate them based on input, but for now the clarity of fixed values is more useful than the complexity of dynamic ones.

Step 2 — The get_match() function

This function takes the player's name as an argument and returns the randomly selected match dictionary. Keeping the selection logic inside its own function means you can call it from anywhere and it stays easy to test.

python 
def get_match(player_name):
    result = random.choice(matches)
    print(f"\nFinding your match, {player_name}...")
    print(f"\nYour match is: {result['name']}")
    print(f"Compatibility score: {result['score']}%")
    return result
Note

The \n at the start of each print statement adds a blank line before the output. This is purely cosmetic — it makes the terminal output easier to read. You can remove these if you prefer tighter spacing.

Step 3 — The main() function and game loop

The main() function handles the overall game flow. It prints a welcome message, then enters a while True loop. Inside the loop it collects the player's name, calls get_match(), and asks whether to play again. If the player types anything other than "yes", the loop breaks and the program ends cleanly.

python 
def main():
    print("Welcome to Matchmaker!")

    while True:
        name = input("\nEnter your name: ").strip()

        if not name:
            print("Please enter a name to continue.")
            continue

        get_match(name)

        again = input("\nPlay again? (yes/no): ").strip().lower()
        if again != "yes":
            print("Thanks for playing!")
            break

The if not name check guards against an empty input. Without it, the function would print something like "Finding your match, ..." which looks broken. The continue statement skips the rest of the loop body and jumps back to the top, prompting for a name again.

Step 4 — The entry point guard

The final piece is the standard Python entry point pattern. When you run the file directly, __name__ equals "__main__" and main() is called. When the file is imported by another module, this block is skipped. It is a good habit to include it in every Python script.

python 
if __name__ == "__main__":
    main()

The complete program

Below is the full file assembled in order. Copy this into matchmaker.py and run it with python matchmaker.py.

python 
import random

matches = [
    {"name": "Jordan",  "score": 87},
    {"name": "Riley",   "score": 72},
    {"name": "Morgan",  "score": 95},
    {"name": "Avery",   "score": 63},
    {"name": "Quinn",   "score": 81},
    {"name": "Taylor",  "score": 78},
    {"name": "Cameron", "score": 90},
]


def get_match(player_name):
    result = random.choice(matches)
    print(f"\nFinding your match, {player_name}...")
    print(f"\nYour match is: {result['name']}")
    print(f"Compatibility score: {result['score']}%")
    return result


def main():
    print("Welcome to Matchmaker!")

    while True:
        name = input("\nEnter your name: ").strip()

        if not name:
            print("Please enter a name to continue.")
            continue

        get_match(name)

        again = input("\nPlay again? (yes/no): ").strip().lower()
        if again != "yes":
            print("Thanks for playing!")
            break


if __name__ == "__main__":
    main()
spot the bug click the line that contains the bug

The get_match() function below has one bug. Click the line you think is wrong, then hit check.

1 def get_match(player_name):
2 result = random.shuffle(matches)
3 print(f"\nYour match is: {result['name']}")
4 print(f"Compatibility score: {result['score']}%")
5 return result
The fix: Replace random.shuffle(matches) with random.choice(matches). random.shuffle() reorders the list in place and returns None. Assigning None to result then causes a TypeError on line 3 when the code tries to access result['name']. random.choice() returns a single item from the list, which is what the rest of the function expects.

Extending the Game

Once the base version works, several small changes make the game noticeably richer without requiring advanced Python knowledge.

To prevent the same match from appearing twice in a row, store the previous result and use a simple loop to keep picking until you get a different one. To make scores feel dynamic, replace the fixed integer values with random.randint(60, 99) directly in the matches list or generate them inside get_match(). To let players build their own match list, replace the hardcoded data with a short loop that calls input() several times before the game starts.

Watch Out

If you modify the matches list inside get_match() — for example by using matches.remove() to avoid repeats — the list will eventually be empty, and random.choice() will raise an IndexError. Guard against this by checking if not matches before the call and repopulating the list or breaking the loop.

Matchmaker game flow — from main() through input validation to random.choice().

How to Build a Matchmaker Game in Python

Follow these six steps to go from an empty file to a working matchmaker game. Each step corresponds to a code section covered earlier in this tutorial.

  1. Set up your file and import the random module

    Create a new file named matchmaker.py and add import random on the first line. This is required before any call to random.choice().

  2. Build the matches list

    Define a module-level list called matches. Each element is a dictionary with a name key (string) and a score key (integer). Add as many entries as you like — seven is a good starting number.

  3. Write the get_match() function

    Define def get_match(player_name):. Inside it, call random.choice(matches) and assign the result to a variable. Print the player's name, the match name, and the score using f-strings, then return the result dictionary.

  4. Print the result with an f-string

    Use f"\nYour match is: {result['name']}" and f"Compatibility score: {result['score']}%". The \n adds a blank line before each print for readability in the terminal.

  5. Add the game loop inside main()

    Write def main(): with a while True loop. Collect the player's name with input(), validate it is not empty, call get_match(), then ask whether to play again. Use break to exit when the answer is not "yes".

  6. Guard the entry point and run the file

    Add if __name__ == "__main__": main() at the bottom. Save the file. Open a terminal, navigate to the file's directory, and run python matchmaker.py.

"Functions should do one thing. They should do it well. They should do it only." — Robert C. Martin, Clean Code

Python Learning Summary Points

  1. The random module must be imported before use. random.choice(seq) picks one item from a sequence and returns it. It does not modify the original sequence.
  2. Storing related data as dictionaries inside a list gives you a flexible structure. You can access values by key (result['name']) and add more attributes to each match later without breaking the rest of the code.
  3. Separating concerns across functions — one function for the matching logic, one for the game loop — makes code easier to read, test, and extend. The if __name__ == "__main__" guard is a best practice for every Python script.

The matchmaker game covers enough ground to give you a solid foundation for your next project. The same pattern — define data, write a function to process it, wrap the function in a loop, validate user input — appears in command-line tools, web APIs, and data scripts alike. Practice extending this game by adding features one at a time, and you will find that each new concept you learn fits naturally into the structure you already have.

check your understanding question 1 of 5

Frequently Asked Questions

A matchmaker game introduces lists, the random module, the input() function, basic functions with def, while loops, and conditional logic using if/elif/else. These are core Python fundamentals that apply to nearly every other type of project.

No prior Python experience is required. This tutorial is designed for absolute beginners. You only need Python installed on your computer and a text editor or IDE.

random.choice() selects and returns a single item from a non-empty sequence, such as a list, at random. You must import random before calling it.

The game accepts the player's name as input, stores a list of potential matches with compatibility scores, and uses random.choice() to select one. It then prints the match name and score. Each run produces a different result because of the random selection.

A list is an ordered collection of items accessed by index, such as matches[0]. A dictionary stores key-value pairs accessed by key, such as match['name']. In this tutorial, each match is stored as a dictionary inside a list, combining both structures.

The while loop keeps the game running until the player chooses to quit. Without it, the program would run once and exit. The loop checks the player's input after each round and continues or breaks based on the response.

Open a terminal or command prompt, navigate to the folder containing your file using the cd command, and run python matchmaker.py (or python3 matchmaker.py on some systems). The program will start and prompt you for input.

strip() removes any leading and trailing whitespace characters from a string, including spaces, tabs, and newlines. Calling it on input() results prevents accidental blank inputs caused by extra spaces the user may have typed.

back to top