How Python Resolves Module Paths and Fixes Import Errors

Import errors are the most common stumbling block for Python beginners — and for good reason. Python uses a layered system of directories, environment variables, and installation records to locate your code, and a single misplaced file or a wrong working directory is enough to break everything. Once you understand the mental model, though, you will fix these errors in seconds instead of minutes.

The mental model: where am I, where do I want to go?

Every time Python sees an import statement, it asks one question: in which directories should I look for this name? The answer lives in a list called sys.path. Python walks that list from top to bottom and imports the first match it finds.

import sys

# Print every directory Python will search, in order
for i, path in enumerate(sys.path):
    print(f"{i}: {path}")

Run this at the top of any script and you immediately see the full search order. The typical output looks like this:

/home/user/my-project          ← directory of the script you ran
/usr/lib/python311.zip
/usr/lib/python3.11
/usr/lib/python3.11/lib-dynload
/home/user/my-project/.venv/lib/python3.11/site-packages  ← installed packages

The three sources that populate sys.path are:

The script’s directory — added automatically when you run python script.py
The standard library — Python’s built-in modules (os, json, datetime, …)
site-packages — third-party packages installed via pip or uv

How virtual environments affect sys.path

When you activate a virtual environment, Python swaps out the site-packages entry to point at the environment’s isolated directory instead of the global one. That is the entire mechanism — nothing more magical than a directory swap.

# Without an active venv — points to global site-packages
python -c "import sys; print([p for p in sys.path if 'site-packages' in p])"
# ['/usr/lib/python3.11/site-packages']

# After activating .venv
source .venv/bin/activate
python -c "import sys; print([p for p in sys.path if 'site-packages' in p])"
# ['/home/user/my-project/.venv/lib/python3.11/site-packages']

Always activate your virtual environment before running your project scripts. If you see ModuleNotFoundError for a package you know you installed, a deactivated venv is the most likely culprit.

Absolute vs relative imports

Within a package you can reference other modules in two ways. Always prefer absolute imports — they are unambiguous and work regardless of how you run the file.

Absolute imports (recommended)
Relative imports (use with caution)

Absolute imports spell out the full path from the project root. They work whether you run the file directly, import it as a module, or run it with pytest.

# src/weather_analysis/main.py

# Full path from the package root — always clear, never ambiguous
from weather_analysis.data_fetcher import fetch_weather
from weather_analysis.data_processor import calculate_stats
from weather_analysis.visualizer import plot_temperature

You can use absolute imports anywhere in your project, including in test files:

# tests/test_data_processor.py
from weather_analysis.data_processor import calculate_stats

def test_average_temperature():
    temps = [10.0, 15.0, 20.0]
    assert calculate_stats(temps)["average"] == 15.0

Relative imports use leading dots to mean “current package” (.) or “parent package” (..). They work inside packages but break when you run the file directly as a script.

# src/weather_analysis/main.py
from .data_fetcher import fetch_weather    # same package
from .data_processor import calculate_stats
from ..config import API_TIMEOUT           # parent package

If you run python src/weather_analysis/main.py directly you will see:

ImportError: attempted relative import with no known parent package

Use relative imports only inside library code that will never be run as __main__.

The PYTHONPATH environment variable

PYTHONPATH is a colon-separated (or semicolon-separated on Windows) list of directories that Python prepends to sys.path before adding the script directory. It is useful for quickly making your project root importable without installing the package.

macOS / Linux
Windows (PowerShell)
.env file approach

# Add the current directory to PYTHONPATH for this shell session
export PYTHONPATH=.

# Now run your script — Python can find packages at the project root
python src/weather_analysis/main.py

# Or set it inline for a single command
PYTHONPATH=. python src/weather_analysis/main.py

# Set for this session
$env:PYTHONPATH = "."

# Run your script
python src\weather_analysis\main.py

If your project uses python-dotenv, you can set PYTHONPATH inside .env so it is picked up automatically:

# .env
PYTHONPATH=.
API_KEY=your-secret-key

from dotenv import load_dotenv
load_dotenv()  # reads .env and sets environment variables

Setting PYTHONPATH globally in your shell profile (~/.bashrc, ~/.zshrc) can cause unexpected behaviour across unrelated projects. Prefer per-project solutions like editable installs or the -m flag instead.

Running scripts correctly with the `-m` flag

The single most reliable way to run a Python module inside a package is the -m flag. It tells Python to run the file as a module, not as a standalone script, which correctly sets up the package hierarchy.

# Always run from the project root
cd my-project

# WRONG — Python adds src/weather_analysis/ to sys.path,
# so absolute imports like 'from weather_analysis.x import y' break
python src/weather_analysis/main.py

# RIGHT — Python adds the current directory to sys.path
# and runs weather_analysis/main.py as part of the package
python -m weather_analysis.main

Notice the dot notation (weather_analysis.main) — no .py extension and no slashes.

Editable installs and the src layout

If you use the src/ layout (recommended), your package is not on sys.path by default because it lives inside the src/ wrapper. The cleanest fix is an editable install, which creates a special link so Python can always find your package — even as you edit the source files.

# Install your own package in editable mode
pip install -e .

# or with uv (much faster)
uv pip install -e .

After this, from weather_analysis.data_fetcher import fetch_weather works from anywhere — in scripts, tests, notebooks, and the Python REPL — without setting PYTHONPATH or using sys.path.append.

# pyproject.toml — minimum needed for an editable install
[project]
name = "weather-analysis"
version = "0.1.0"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/weather_analysis"]

The `name == "main"` guard

Every Python file has a built-in __name__ variable. When you run a file directly, Python sets __name__ to "__main__". When the same file is imported by another module, __name__ is set to the module’s dotted path instead. Use this to write code that runs only when executed directly:

# src/weather_analysis/data_processor.py

def calculate_stats(temperatures: list[float]) -> dict:
    """Return average, min, and max temperature."""
    return {
        "average": sum(temperatures) / len(temperatures),
        "min": min(temperatures),
        "max": max(temperatures),
    }

# This block is IGNORED when you do:  from weather_analysis.data_processor import calculate_stats
# It RUNS only when you do:           python -m weather_analysis.data_processor
if __name__ == "__main__":
    sample = [12.5, 18.0, 9.3, 22.1, 15.6]
    stats = calculate_stats(sample)
    print(f"Average: {stats['average']:.1f}°C")
    print(f"Min: {stats['min']}°C  |  Max: {stats['max']}°C")

Diagnosing and fixing import errors

ModuleNotFoundError: No module named 'X'

Python searched every directory in sys.path and found nothing named X.Diagnose it:

import sys
print("sys.path entries:")
for p in sys.path:
    print(" ", p)

Common causes and fixes:

Cause	Fix
Package not installed	`uv add X` or `pip install X`
Wrong virtual environment active	`source .venv/bin/activate`
Running from wrong directory	`cd` to project root, then `python -m package.module`
Package in `src/` but not installed	`pip install -e .`

FileNotFoundError: No such file or directory

This applies to data files (CSV, JSON, images), not to Python modules. Python looked for a file at the path you provided relative to the current working directory, not relative to the script file.

import os

# Where is Python looking from?
print("Current working directory:", os.getcwd())
print("Contents:", os.listdir("."))

Use pathlib to build paths relative to the script file itself — this works no matter where you run from:

from pathlib import Path

# __file__ is the absolute path of the current script
HERE = Path(__file__).parent
DATA_FILE = HERE / ".." / "data" / "weather.csv"

with open(DATA_FILE) as f:
    content = f.read()

ImportError: attempted relative import with no known parent package

You used a relative import (.module) but ran the file as a standalone script instead of as part of a package.

# This triggers the error
python src/weather_analysis/data_processor.py

# Fix: run as a module from the project root
python -m weather_analysis.data_processor

Or switch the relative import to an absolute one.

Mixing up slashes (files) and dots (modules)

File paths use / (or \ on Windows). Module paths use .. They are not interchangeable.

# WRONG — SyntaxError
import data/helpers

# WRONG — this imports a standard library module, not your file
import os.path

# RIGHT — imports data/helpers.py as a module
import data.helpers
from data.helpers import clean_rows

Circular imports

Module A imports from module B, and module B imports from module A. Python partially initialises one of them and you get an ImportError or AttributeError.

# BAD: circular dependency
# module_a.py
from module_b import helper_b   # module_b imports from module_a...

# module_b.py
from module_a import helper_a   # ...creates a circle

Fix circular imports by extracting shared code into a third module (utils.py, models.py) that neither module_a nor module_b imports.

Practical import patterns

# ── Standard library first ──────────────────────────────────────────────────
import os
import sys
from pathlib import Path
from datetime import datetime, timedelta

# ── Third-party packages second ─────────────────────────────────────────────
import requests
import pandas as pd
import matplotlib.pyplot as plt

# ── Your own project code last ───────────────────────────────────────────────
from weather_analysis.data_fetcher import fetch_weather
from weather_analysis.data_processor import calculate_stats
from weather_analysis.visualizer import plot_temperature

Follow the isort convention: group imports as (1) standard library, (2) third-party, (3) local, with a blank line between each group. The ruff linter enforces this automatically — add it to your project with uv add --dev ruff.

Organizing Code

Learn how to split a large script into clean, reusable modules

Project Development

SQL & Databases

Data Analysis

How Python Resolves Module Paths and Fixes Import Errors

The mental model: where am I, where do I want to go?

How virtual environments affect sys.path

Absolute vs relative imports

The PYTHONPATH environment variable

Running scripts correctly with the `-m` flag

Editable installs and the src layout

The `name == "main"` guard

Diagnosing and fixing import errors

Practical import patterns

Organizing Code

​The mental model: where am I, where do I want to go?

​How virtual environments affect sys.path

​Absolute vs relative imports

​The PYTHONPATH environment variable

​Running scripts correctly with the -m flag

​Editable installs and the src layout

​The __name__ == "__main__" guard

​Diagnosing and fixing import errors

​Practical import patterns

Organizing Code

The mental model: where am I, where do I want to go?

How virtual environments affect sys.path

Absolute vs relative imports

The PYTHONPATH environment variable

Running scripts correctly with the `-m` flag

Editable installs and the src layout

The `name == "main"` guard

Diagnosing and fixing import errors

Practical import patterns