Running Scripts from the Command Line

diagram python script.py and python -m are not the same command mermaid

  flowchart TD
  A["python pkg/mod.py"] --> B["sys.path[0] = pkg/"]
  B --> C["'pkg' itself is NOT importable"]
  C --> D["from pkg import mod -> ModuleNotFoundError"]
  E["python -m pkg.mod"] --> F["sys.path[0] = the current directory"]
  F --> G["'pkg' is importable"]
  G --> H["relative and absolute imports both work"]
  I["__name__"] --> J["'__main__' either way -- the guard behaves the same"]

Both run the same file, but they set up the import system differently. Running a path puts that file's own directory first on sys.path; running a module puts the current directory there instead. That single difference decides whether the file can import the package it lives in.

Measured: the same package, two ways of starting it

Same directory, same cwd, one difference:

Command	sys.path[0]
python pkg/mod.py	<project>/pkg — the script’s directory
python -m pkg.mod	<project> — the current directory

And the consequence, with a module that does from pkg import mod:

Command	Result
python pkg/mod2.py	ModuleNotFoundError: No module named 'pkg'
python -m pkg.mod2	works

This is the single most common “but it imports fine in my editor” problem. The file has not changed and neither has the working directory — only the way the interpreter was invoked.

The rule: anything inside a package should be started with -m. A plain python path/to/file.py is for standalone scripts that import nothing local. Adding sys.path.append("..") to work around it appears to fix the symptom and breaks as soon as the script is run from anywhere else.

Basic run

bash

python my_script.py

Use a virtual environment

• isolate dependencies
• avoid “works on my machine”

Working directory tip

Many scripts break because they assume the current directory.

Prefer pathlib.Path(__file__):

base_dir.py

from pathlib import Path
 
BASE_DIR = Path(__file__).resolve().parent
print(BASE_DIR)

🧪 Try It Yourself

Exercise 1 – List Files with os.listdir

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Join Paths with os.path.join

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Write and Read a File

pch.exerciseTag pch.exerciseTitle