Introduction

Running Python with python script.py and running it with python -m package.module are not equivalent. Both execute code, but they set up imports, module names, and package context differently.

That difference matters most when your code lives inside a package. If you choose the wrong form, relative imports may fail, sys.path may not be what you expect, and the program may behave differently depending on where it was launched.

Direct Script Execution

When you run a file directly, Python executes that file path as the main program.

python app.py

Inside the script, __name__ becomes "__main__", and the directory containing the script is placed near the front of sys.path.

That is fine for standalone files, quick experiments, and single-module utilities. It becomes awkward when the file is really part of a package and expects package-relative imports.

For example, suppose you have this structure:

1project/
2  mypkg/
3    __init__.py
4    app.py
5    utils.py

If app.py contains a relative import like from .utils import helper, running it directly usually fails.

Module Execution With -m

When you use -m, Python resolves the target through the import system and then executes it as the main module.

python -m mypkg.app

That changes two important things:

• Python treats mypkg.app as part of package mypkg
• import resolution behaves as package code expects

This is why -m is the recommended way to run code that lives inside a package.

Example: Relative Imports

Here is a minimal example that works with -m:

1# mypkg/utils.py
2
3def helper():
4    return "ready"

1# mypkg/app.py
2from .utils import helper
3
4print(helper())

Run it from the project root with:

python -m mypkg.app

If you instead try python mypkg/app.py, Python treats the file as a top-level script, so the relative import has no package context and usually raises an import error.

__name__ And __package__

In both styles, the executed module usually sees __name__ == "__main__". The difference is that module execution with -m also sets package-related metadata appropriately.

That means package-relative imports and resource lookups behave more naturally. This is the key reason many tools, frameworks, and library docs instruct you to run modules with python -m ....

Standard Library And Installed Modules

-m is also how you run modules that are not represented by a file path you want to type directly. Common examples include:

python -m venv .venv
python -m http.server 8000
python -m pip install requests

In those cases, -m asks Python to locate the module the same way imports work, then execute it.

When To Use Each Style

Use direct file execution when:

• the code is a standalone script
• package context is irrelevant
• you want the simplest possible command

Use -m when:

• the target lives inside a package
• you rely on relative imports
• you want behavior consistent with normal Python imports
• you are invoking a standard library or installed module as a command

Common Pitfalls

• Running a package module as a file and then blaming the import statement.
• Assuming python file.py and python -m package.file set up the same import context.
• Launching python -m from the wrong working directory so the package is not importable.
• Using absolute imports that accidentally work only because of a specific sys.path layout.
• Forgetting that -m takes a module name, not a file path.

Summary

• 'python script.py runs a file directly as the main program.'
• 'python -m package.module runs code through Python's import system.'
• '-m is usually the right choice for modules inside packages.'
• Relative imports often fail with direct file execution but work with -m.
• Use direct execution for simple standalone scripts and -m for package-aware entry points.