# Your Own Modules and Packages

Any .py file is a module another file can import, so a growing program is split into files by job, a folder of them with \_\_init\_\_.py becomes a package, and the \_\_name\_\_ check keeps a file's own test lines from running when it's imported.

Apprentice · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Split a program into modules of your own and a package, and bring them into another file with import or from … import
- Guard a file's own code with if \_\_name\_\_ == "\_\_main\_\_" so it runs when the file is run, not when it is imported

## Key takeaways

- Any .py file is a module. A file in the same folder brings it in with import scores (the file name without .py) or from scores import add_points.
- Importing a module runs it from top to bottom, so lines at its bottom that print or test run in every program that imports it.
- Python sets __name__ to "__main__" in the file you run, and to the module's name in a file being imported. if __name__ == "__main__" uses that to keep a file's own code to itself.
- A package is a folder of modules with an __init__.py file, and from gamenight.scores import add_points reaches a module inside it.

A program starts as one file and grows. At 50 lines it's fine; at 400 you scroll up and down hunting for a function, and when a second script needs that function, you copy it, and the two copies slowly drift apart. Splitting the code into files, each with one job, fixes both. It's also how every project you'll clone is organized, and how a test file reaches the code it tests.

The example is Game Night: a group of friends who play board games on Fridays, and a small program that keeps their scores.

## A second file is a module

Game night's score-keeping functions are wanted by more than one script, so they move out of the big file into one of their own, `scores.py`, which holds those functions and nothing else:

```python
def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")
```

A file like this is a **module**: a file of Python code that another file can use. You don't need anything special to make one: every `.py` file is a module. In the same folder, `main.py` brings it in with `import`, followed by the file's name without `.py`, and calls each function through the module's name and a dot:

```python
import scores

totals = {}
scores.add_points(totals, "Ana", 12)
scores.add_points(totals, "Ben", 9)
scores.add_points(totals, "Ana", 5)
scores.show(totals)
```

Running `python main.py` (`python3` on a Mac outside a virtual environment) prints:

```text
Ana: 17
Ben: 9
```

`scores.add_points` is read "scores dot add points": the `add_points` that lives in `scores`. To write the names on their own instead, bring them in by name with `from scores import add_points, show`, and then call `add_points(totals, "Ana", 12)`.

Python looks for `scores.py` in the folder of the file you run, then among its own modules and the packages you've installed. A typo, such as `import score`, stops with `ModuleNotFoundError: No module named 'score'`. And never name your file after a module Python already has, such as `random.py`: Python finds your file first, and every `import random` in that folder gets yours instead.

## Importing runs the file

While writing `scores.py`, it's natural to try it out with a few lines at the bottom:

```python
def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")


# Trying the module out while writing it
practice = {}
add_points(practice, "Test", 3)
show(practice)
```

```text
Test: 3
```

Now run `main.py`, which uses `from scores import add_points, show` and adds Ana's 12 and Ben's 9, and a stranger turns up:

```text
Test: 3
Ana: 12
Ben: 9
```

Importing a module runs it from top to bottom, once, the first time it's imported. The `def` lines define the functions, which is what `main.py` wanted; the try-out lines at the bottom run too, which it didn't.

## The file being run: \`\_\_name\_\_\`

Python gives every module a variable called `__name__` (read "dunder name", short for "double underscore name"). In the file you run, it's the text `"__main__"`. In a file being imported, it's the module's name. Two one-line files show it: `scores.py` holds `print("scores.py says its __name__ is", __name__)`, and `main.py` holds `import scores`, then a line that prints its own `__name__`:

```text
scores.py says its __name__ is scores
main.py says its __name__ is __main__
```

Run `scores.py` by itself, and it says `__main__`. So a file can ask, "am I the one being run?" Put the try-out lines under that question, indented:

```python
def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")


if __name__ == "__main__":
    practice = {}
    add_points(practice, "Test", 3)
    show(practice)
```

```text
Test: 3
```

`if __name__ == "__main__":` reads "if this file is the one being run". `python scores.py` still prints `Test: 3`, and `python main.py` prints only Ana's and Ben's scores. You'll see this line at the bottom of many Python files.

## A package: a folder of modules

When the modules pile up, put them in a folder. A **package** is a folder of modules with a file named `__init__.py` (read "dunder init dot py") inside, which tells Python the folder is a package. It can be empty.

```text
game-night/
├── main.py
└── gamenight/
    ├── __init__.py
    ├── dice.py
    └── scores.py
```

`main.py` reaches inside the package with a dot between the folder and the module, either way:

```python
from gamenight import dice
from gamenight.scores import add_points, show

totals = {}
add_points(totals, "Cleo", dice.total([6, 4]))
show(totals)
```

```text
Cleo: 10
```

Here `dice.py` holds one function, `total(rolls)`, which returns `sum(rolls)`. Run programs from the folder that holds the package (`game-night/`), so Python finds `gamenight`. A package can also be run as a program: `python -m gamenight` runs the file `gamenight/__main__.py` inside it, if the package has one.

## Check yourself

2 questions to try on the lesson page.

## So what

Small files with one job each are easier to find your way around, to reuse without copying, and to test, which is why every real Python project, and every library you'll install, is a package of modules.

## Key terms

- [Module](https://www.ask-codey.com/glossary/module)
- [Package](https://www.ask-codey.com/glossary/package)
- [\_\_init\_\_.py](https://www.ask-codey.com/glossary/init-py)
- [Main Guard (if \_\_name\_\_ == "\_\_main\_\_")](https://www.ask-codey.com/glossary/main-guard-if-name-main)
- [from … import](https://www.ask-codey.com/glossary/from-import)

## Related

- [import and the Standard Library](https://www.ask-codey.com/lessons/python-modules-import-and-standard-library)
- [Virtual Environments and pip](https://www.ask-codey.com/lessons/python-venv-and-pip)

Source: https://www.ask-codey.com/lessons/python-modules-your-own
