Python paths

The most confusing part of Python

Understanding paths is probably the most confusing part when starting with Python. You’ll make mistakes with file paths and imports, and that’s totally fine. That’s how everyone learns. This page gives you a quick introduction. Some parts might not be completely clear right now, but as you practice, it will click. Come back to this page when you run into path issues - it happens to everyone!

The mental model

When working with multiple files, always think about two things:

Where am I? - What folder is my Python script in?
Where do I want to go? - What file or module do I need?

Then navigate:

Going down into subfolders: Use / for files, . for imports
Going up to parent folders: Use ../ for files, add to sys.path for imports
Same folder: Just use the filename

# From script.py, accessing different locations:
"data/sales.csv"        # Down into data folder
"../config.json"        # Up one level
"helper.py"             # Same folder

# For imports:
import helper           # Same folder - no path needed!
import data.processor   # Down into data folder

# Parent folder imports need sys.path:
import sys
sys.path.append("..")   # Add parent to path
import parent_module    # Now you can import

The simple rule

When Python runs, it has a “current working directory” - the folder it’s currently in. All file paths start from there.

import os

# See where Python is right now
print(os.getcwd())

Try this - it shows you exactly where Python is looking for files.

Finding your files

Let’s say you have this structure:

my-project/
├── script.py
├── data.txt
└── folder/
    └── other.txt

If you run script.py:

# Python can find these:
open("data.txt")           # Same folder
open("folder/other.txt")   # Subfolder

# Python CAN'T find these (they don't exist from here):
open("other.txt")          # Wrong! It's in a subfolder
open("../parent.txt")      # Looking in parent folder

Files vs modules - key difference

Python handles regular files and Python modules differently: Regular files (CSV, TXT, JSON):

Use open() or file-reading functions
Need the exact path from your current directory
Use forward slashes: data/sales.csv

# Reading a CSV file - needs exact path
with open("data/sales.csv", "r") as file:
    content = file.read()

Python modules (importing code):

Use import statements
Python searches in multiple locations (sys.path)
Use dots instead of slashes: folder.module

# Importing a module - Python searches for it
import mymodule                    # Looks for mymodule.py
from folder.utils import helper    # Looks for folder/utils.py

How Python finds modules

Python looks for modules (other .py files) in specific directories stored in sys.path. You can see these places by running:

import sys
print(sys.path)  # List of folders Python checks

The lookup order includes:

The folder containing the script you ran.
Python’s built-in standard library folders.
Installed third-party packages (located in site-packages directory).

Absolute vs. Relative Imports

Within a package, you can refer to other modules in two ways:

Absolute Import: Uses the full path from the project root.
from mypackage.utils import format_text

Relative Import: Uses leading dots (.) to refer to modules relative to the current module.

from .utils import format_text  # . means current directory
from ..core import database    # .. means parent directory

Best Practice: Always prefer Absolute Imports.Absolute imports are much clearer, easier to read, and don’t break if you move a file to a different directory. Furthermore, if you run a file containing relative imports directly as a script (e.g., python mypackage/utils.py), Python will raise: ImportError: attempted relative import with no known parent package.

Package Initialization: `init.py` and `all`

When you import from a package, Python runs the package’s __init__.py file. You can define what gets exposed to the public API when a user imports your package using the special __all__ list:

# mypackage/__init__.py
# Only expose 'utils' module when using wildcard import 'from mypackage import *'
__all__ = ['utils']

The `name == "main"` Block

When a Python file is run directly, Python sets a special built-in variable __name__ to "__main__". If the file is imported by another script, __name__ is set to the file’s actual module name instead. We use this block to write code that only executes when the file is run directly, but is ignored when imported as a library:

# calculator.py

def add(a, b):
    return a + b

# This testing code will only run if you execute 'python calculator.py'
# It will NOT run if you do 'import calculator' in another script
if __name__ == "__main__":
    print("Testing calculator...")
    print(add(10, 5) == 15)  # True

Running Modules & Troubleshooting Import Errors

When working with local modules and packages, developers frequently run into path-related errors. Here is how to understand and solve them:

The Scenario

Suppose you have a project structured like this:

myproject/
├── main.py
└── mypackage/
    ├── utils.py
    └── helper.py

And inside utils.py, you have an absolute import: from mypackage.helper import greet.

The Mistake

If you navigate inside the mypackage/ folder and run python utils.py, Python will crash with: ModuleNotFoundError: No module named 'mypackage'. Why? Because Python adds the directory of the executed script (myproject/mypackage/) to sys.path. It does not know that mypackage exists one folder level up.

The Solutions

Solution 1: Run as a module using the `-m` flag (Recommended)

Always run your Python scripts from the project root directory (e.g., myproject/) using the -m (module) flag. This preserves the package hierarchy and correctly configures sys.path.

# 1. Navigate to the project root directory
cd myproject

# 2. Run the module using dot notation (no .py extension!)
python -m mypackage.utils

Solution 2: Set the `PYTHONPATH` Environment Variable

You can manually tell Python where to look for modules by setting the PYTHONPATH environment variable to your project root directory.

macOS / Linux:

export PYTHONPATH=.
python mypackage/utils.py

Windows (PowerShell):

$env:PYTHONPATH="."
python mypackage/utils.py

Adding your own folders manually

Sometimes you need Python to look in additional places:

import sys

# Add a folder to Python's search path
sys.path.append("/path/to/my/folder")

# Now you can import from that folder
import mymodule

Common example - importing from a parent folder:

import sys
import os

# Go up one level from current script
parent = os.path.dirname(os.path.dirname(__file__))
sys.path.append(parent)

Common mistakes

FileNotFoundError: No such file or directory

This happens when Python can’t find your file. The file path is wrong or you’re running from a different folder than expected.

# Debug it:
import os
print("Looking in:", os.getcwd())
print("Files available:", os.listdir())

Fix: Use the correct path from your current directory, or use absolute paths.

ModuleNotFoundError: No module named 'X'

Python can’t find the module you’re trying to import. It’s not in any of the folders Python searches.

# See where Python looks:
import sys
print("Python searches in:", sys.path)

Fix: Make sure the module is in one of those folders, or add its folder to sys.path.

Mixing up files and modules

Remember: regular files use paths with slashes, Python modules use dots.

# Wrong:
import data/helpers  # SyntaxError!

# Right:
import data.helpers  # For data/helpers.py

Running from the wrong folder

Your script works in VS Code but not in terminal? You’re probably in a different folder.

# Always check first:
import os
print("Running from:", os.getcwd())

Fix: Navigate to the right folder in terminal, or use the VS Code play button.

Using backslashes on Mac/Linux

Windows uses backslashes, but Mac/Linux use forward slashes. Use forward slashes - they work everywhere!

# Works everywhere:
"data/file.csv"

# Only works on Windows:
"data\\file.csv"

Keep it simple

Remember, everyone struggles with paths at first. For now:

Keep related files in the same folder
Use the VS Code play button (it’s predictable)
When confused, print os.getcwd() to see where you are
Come back to this page when you hit path errors

The mental model: Know where you are, know where you want to go, then navigate with / for files. For imports, same folder needs no path, subfolders use ., parent folders need sys.path.

Organizing code

Learn to split code into reusable functions and files

Essential Tools

Environment & secrets

Practical Python

Project Development

The most confusing part of Python

The mental model

The simple rule

Finding your files

Files vs modules - key difference

How Python finds modules

Absolute vs. Relative Imports

Package Initialization: `init.py` and `all`

The `name == "main"` Block

Running Modules & Troubleshooting Import Errors

The Scenario

The Mistake

The Solutions

Solution 1: Run as a module using the `-m` flag (Recommended)

Solution 2: Set the `PYTHONPATH` Environment Variable

Adding your own folders manually

Common mistakes

Keep it simple

Organizing code

​The most confusing part of Python

​The mental model

​The simple rule

​Finding your files

​Files vs modules - key difference

​How Python finds modules

​Absolute vs. Relative Imports

​Package Initialization: __init__.py and __all__

​The __name__ == "__main__" Block

​Running Modules & Troubleshooting Import Errors

​The Scenario

​The Mistake

​The Solutions

​Solution 1: Run as a module using the -m flag (Recommended)

​Solution 2: Set the PYTHONPATH Environment Variable

​Adding your own folders manually

​Common mistakes

​Keep it simple

Organizing code

The most confusing part of Python

The mental model

The simple rule

Finding your files

Files vs modules - key difference

How Python finds modules

Absolute vs. Relative Imports

Package Initialization: `init.py` and `all`

The `name == "main"` Block

Running Modules & Troubleshooting Import Errors

The Scenario

The Mistake

The Solutions

Solution 1: Run as a module using the `-m` flag (Recommended)

Solution 2: Set the `PYTHONPATH` Environment Variable

Adding your own folders manually

Common mistakes

Keep it simple