python -m name finds a module or package by its import name and runs it as the main program. Use python -m pip --version to see the pip available to that interpreter. To run a particular source file by path, use a command such as python report.py.
What each part of python -m pip --version means
First select the interpreter. On a Linux system that may mean python3. For a project tool it can be the executable inside .venv. Then write -m followed by a module name such as pip. Arguments after the module name belong to its command line. For example, --version belongs to pip in python -m pip --version.
A module name often resembles a filename, but it is not a path. Do not put a .py extension after the name. To run a supported command in the example.tools module, use python -m example.tools from an environment where that package can be found. Typing a path with slashes after -m asks for a different operation than executing a file.
Choose the command that preserves package context
Suppose a program depends on relative imports within a package. Running its source file by path may leave it without the package context those imports need. Running the documented module entry point can preserve that context. Python still needs to find the package, so use the project setup author specifies. The fix typically involves running the supported command within the right environment rather than editing imports until both invocations happen to work.
For a package executed as a command, Python looks for code from __main__.py inside it. A normal library package may not provide that file. If you see an error saying that a package cannot be directly executed, consult its documentation for a supported module or console command.
Keep imports free to be imports
A file can define a main() function and call it only when the file or module is the main program. The familiar if __name__ == "__main__": guard protects the command invocation from an ordinary import. Definitions at the top level are still evaluated as part of importing the module. Put actions such as reading a user file or opening a network connection behind a deliberate call.
This design helps tests import helpers without accidentally running a whole command. A library user can reuse the calculation. A command-line user can invoke the same code through a supported entry point.
Try direct execution and import side by side
Save this example as status_demo.py in an ordinary working folder.
def status():
return "ready"
if __name__ == "__main__":
print(status())
From that folder, run python status_demo.py and python -m status_demo. Each prints ready. Try python -c "import status_demo; print(status_demo.status())". It prints the result of the deliberate function call only. The module did not start its command during import. This difference is useful for libraries, tests, and jobs that need to call one function without re-running an entire program.
Diagnose a module command from the correct folder
A module command can fail after you move to a different folder even if the source file has stayed put. Python resolves the module name using its import path. If the supported command is python -m package, follow the project's installation instructions or start from the documented folder. If the entry point is a standalone file, follow the script launch instructions and supply the file path.
Check what an installation command tells you
python -m pip --version shows pip's location and Python version. This is useful if a bare pip resolves to a different environment. If it says there is no module named pip, the interpreter started but could not locate pip in that environment. That is a different diagnosis from a shell that could not find python at all.
Write the launch method in the README. A module command is particularly useful when it anchors a tool to an interpreter and when running arbitrary paths would otherwise create inconsistent imports.