Execution of Python code with -m option or not

by

When you use the -m command-line flag, Python will import a module or package for you, then run it as a script. When you don’t use the -m flag, the file you named is run as just a script.

The distinction is important when you try to run a package. There is a big difference between:

python foo/bar/baz.py

and

python -m foo.bar.baz

as in the latter case, foo.bar is imported and relative imports will work correctly with foo.bar as the starting point.

Demo:

$ mkdir -p test/foo/bar
$ touch test/foo/__init__.py
$ touch test/foo/bar/__init__.py
$ cat << EOF > test/foo/bar/baz.py 
> if __name__ == "__main__":
>     print __package__
>     print __name__
> 
> EOF
$ PYTHONPATH=test python test/foo/bar/baz.py 
None
__main__
$ PYTHONPATH=test python -m foo.bar.baz 
foo.bar
__main__

As a result, Python has to actually care about packages when using the -m switch. A normal script can never be a package, so __package__ is set to None.

But run a package or module inside a package with -m and now there is at least the possibility of a package, so the __package__ variable is set to a string value; in the above demonstration it is set to 'foo.bar', for plain modules not inside a package it is set to an empty string.

As for the __main__ module, Python imports scripts being run as it would import regular modules. A new module object is created to hold the global namespace and is stored in sys.modules['__main__']. This is what the __name__ variable refers to, it is a key in that structure.

For packages, you can create a __main__.py module inside and have that run when running python -m package_name; in fact that is the only way you can run a package as a script:

$ PYTHONPATH=test python -m foo.bar
python: No module named foo.bar.__main__; 'foo.bar' is a package and cannot be directly executed
$ cp test/foo/bar/baz.py test/foo/bar/__main__.py
$ PYTHONPATH=test python -m foo.bar
foo.bar
__main__

So, when naming a package for running with -m, Python looks for a __main__ module contained in that package and executes that as a script. Its name is then still set to '__main__' and the module object is still stored in sys.modules['__main__'].

More Related Contents:

  1. What is __init__.py for?
  2. What is the purpose of the -m switch?
  3. What’s the difference between a Python module and a Python package?
  4. Python 3: ImportError “No Module named Setuptools”
  5. Python: importing a sub‑package or sub‑module
  6. Can’t import my own modules in Python
  7. Can’t import my own modules in Python
  8. Python: import module from another directory at the same level in project hierarchy
  9. Flask(‘application’) versus Flask(__name__)
  10. Python modules with identical names (i.e., reusing standard module names in packages)
  11. How to properly use relative or absolute imports in Python modules?
  12. python import module from parent package
  13. What’s the difference between a module and package in Python?
  14. How to reference python package when filename contains a period
  15. How do I unload (reload) a Python module?
  16. How do I get a list of locally installed Python modules?
  17. How do I find the location of Python module sources?
  18. How to list all functions in a module?
  19. Callable modules
  20. How to import module when module name has a ‘-‘ dash or hyphen in it?
  21. List all the modules that are part of a python package?
  22. Importing modules: __main__ vs import as module
  23. Why is the value of __name__ changing after assignment to sys.modules[__name__]?
  24. How do I call setattr() on the current module?
  25. Use a library locally instead of installing it
  26. How to install a Python package from within IPython?
  27. What’s the difference between io.open() and os.open() on Python?
  28. Python error: AttributeError: ‘module’ object has no attribute
  29. Loading environment modules within a python script
  30. How to document Python packages using Sphinx

Leave a Comment