Create Your First Python Project

Single .py files are fine for experiments. But when you start building something you want to keep, reuse, or share, a structured project folder makes everything easier.

Before starting, make sure you can write and run a Python script and install packages with pip.

Create the project folder

Pick a location for your projects. A folder called projects or dev in your home directory works well:

bash

mkdir ~/projects
cd ~/projects

Create a new folder for this project:

bash

mkdir number-guesser
cd number-guesser

Use a descriptive name with hyphens between words. This is the Python convention. Avoid spaces, which can cause problems in terminal commands.

Create the main script

Inside number-guesser, create a file called main.py:

python

import random
 
def get_random_number():
    return random.randint(1, 100)
 
def get_user_guess():
    while True:
        try:
            return int(input("Guess a number between 1 and 100: "))
        except ValueError:
            print("Please enter a valid number.")
 
def main():
    target = get_random_number()
    guess = None
    attempts = 0
 
    print("I am thinking of a number between 1 and 100.")
 
    while guess != target:
        guess = get_user_guess()
        attempts += 1
 
        if guess < target:
            print("Too low.")
        elif guess > target:
            print("Too high.")
 
    print(f"You got it in {attempts} attempts!")
 
if __name__ == "__main__":
    main()

Run it to make sure it works:

bash

python main.py

The if __name__ == "__main__" block is a Python convention. Code inside it only runs when you execute the file directly. If another file imports this one, the main() function does not run automatically. This lets you reuse functions without triggering the full program.

Split code into modules

When main.py grows, move related functions into separate files. Create a new file called game_logic.py:

python

import random
 
def get_random_number():
    return random.randint(1, 100)
 
def check_guess(guess, target):
    if guess < target:
        return "Too low."
    elif guess > target:
        return "Too high."
    return None

Now update main.py to import from game_logic.py:

python

from game_logic import get_random_number, check_guess
 
def get_user_guess():
    while True:
        try:
            return int(input("Guess a number between 1 and 100: "))
        except ValueError:
            print("Please enter a valid number.")
 
def main():
    target = get_random_number()
    guess = None
    attempts = 0
 
    print("I am thinking of a number between 1 and 100.")
 
    while guess != target:
        guess = get_user_guess()
        attempts += 1
        result = check_guess(guess, target)
        if result:
            print(result)
 
    print(f"You got it in {attempts} attempts!")
 
if __name__ == "__main__":
    main()

main.py is now shorter and easier to read. game_logic.py contains functions that are easy to test and reuse in other projects. As your project grows, keep splitting related code into modules with clear names.

Create a requirements.txt

Even if your project only uses the standard library (as this one does with random), adding a requirements.txt is good practice. Create it now so the habit sticks:

bash

python -m pip freeze > requirements.txt

For this project, the file will be empty or contain only pip and setuptools. For a project that uses external packages like requests, the file would list them with versions:

plaintext

requests==2.32.4

If someone clones your project, they can install everything with:

bash

python -m pip install -r requirements.txt

For more details on pip workflows, see install and manage Python packages.

Add a README

Create a README.md file at the root of your project:

markdown

# Number Guesser
 
A simple console game where the player guesses a random number between 1 and 100.
 
## How to run
 
python main.py
 
## Requirements
 
Python 3.10 or later.

A README tells anyone who finds your project (including your future self) what it does and how to run it. The .md extension means Markdown, a simple formatting language that GitHub and many editors render nicely.

The project folder structure

Your project now looks like this:

plaintext

number-guesser/
  main.py
  game_logic.py
  requirements.txt
  README.md

This is a clean, standard layout for a beginner Python project. Every file has a clear purpose. The folder name matches the project name. The structure is flat enough to navigate easily.

For larger projects, you might add subfolders:

plaintext

number-guesser/
  number_guesser/
    __init__.py
    main.py
    game_logic.py
  tests/
    test_game_logic.py
  requirements.txt
  README.md

The __init__.py file makes number_guesser a Python package. It can be empty. The tests/ folder holds automated tests, which you will learn about later when you reach the testing topics. For now, the flat structure is enough.

Use a virtual environment

A clean project pairs naturally with a virtual environment. Virtual environments keep each project's packages isolated from every other project.

Create one inside your project:

bash

python -m venv .venv

Activate it:

• macOS/Linux: source .venv/bin/activate
• Windows: .venv\Scripts\activate

Now when you install packages with pip, they go into .venv instead of your global Python installation. The .venv folder should not be committed to version control. Add it to your .gitignore file:

plaintext

.venv/
__pycache__/

Next steps

Your project is structured and ready to grow. Now set up a virtual environment if you have not already, and learn how to organize your Python workspace for a smooth daily workflow.

When you are ready to learn the language itself, start with Python syntax and indentation in the Python Basics section.