Unlock Python’s Power: Master the -m Flag for Quick Scripts and Tools

This article, excerpted from the "Python Black Magic Guide" (Chapter 2, Section 14), explains how to use Python's -m option to run modules or packages as scripts and demonstrates several practical command‑line shortcuts.

1. Usage Examples

Below are common one‑liner commands that leverage -m:

# python2
$ python -m SimpleHTTPServer 8888
# python3
$ python3 -m http.server 8888

Result:

$ python -m pydoc -p 5200

Result:

$ python -m pdb demo.py

$ python3 -m pip install requests

$ echo '{"name": "MING"}' | python -m json.tool

$ python -m site

Result:

$ python3 -m timeit '-'.join(map(str, range(100)))

Result:

2. Underlying Mechanism

All the commands share the -m option, which tells Python to locate the specified module or package and execute its entry point. When a module is run with -m, Python sets __name__ to __main__, causing any code guarded by if __name__ == '__main__': to run.

For example, the pip package contains a __main__.py file, while json.tool is a submodule whose main() function is invoked when the module is executed.

Typical pattern:

if __name__ == '__main__':
    main()

3. Practical Steps

Add the current directory to PATH: $ export PATH=${PATH}:`pwd` Create a package demo with an __main__.py file:

# __main__.py
print("hello, world")

Run it:

$ python3 -m demo
hello, world

Now add a module foobar.py with a main() function:

# foobar.py
def main():
    print("hello, world")

if __name__ == "__main__":
    main()

Execute:

$ python3 -m demo.foobar
hello, foobar

4. Why Use -m

The -m form abstracts away the physical location of the script; Python’s import system resolves the module, making commands like python -m json.tool far more convenient than invoking the script file directly (e.g., python /usr/lib/python2.7/json/tool.py).