How to Run a Python File in Terminal (Step-by-Step)

by

Running a Python file in the terminal might seem intimidating at first, especially for those who are new to programming or just beginning to explore the world of command-line interfaces. However, once broken down into simple, digestible steps, executing a Python file from the terminal becomes a powerful and efficient method for running scripts, automating tasks, and developing robust applications.

This guide will walk you through a comprehensive, step-by-step process on how to properly run a Python file from the terminal. Whether you’re using Windows, macOS, or Linux, the procedures remain largely the same, with only minor differences. This tutorial aims to be your trusted companion on this journey toward mastering Python execution via the command line.

1. Install Python

Before you can run Python files in the terminal, you need to ensure that Python is installed on your system. Most macOS and Linux distributions come with Python pre-installed, but often in outdated versions. Here’s how to check and install Python:

  • Check if Python is installed: Open your terminal and type python --version or python3 --version. You should see something like Python 3.11.4.
  • If Python is not installed:
    • Windows: Download the installer from python.org.
    • macOS: Use brew install python if Homebrew is installed.
    • Linux: Use your distro’s package manager, such as sudo apt install python3 for Debian/Ubuntu.

It is advisable to use a recent version of Python (3.7 or later) to ensure compatibility with modern scripts and modules.

2. Write a Python Script

Before you run a Python file, you need to have one. Here’s how to create a simple script:

  1. Open your preferred text editor (VS Code, Atom, Sublime Text, or even Notepad).
  2. Write the following Python code:
print("Hello, world!")
  1. Save the file as hello.py.

Confirm the script is saved with a .py extension. This tells the terminal that it is a Python file and should be interpreted as such.

3. Open the Terminal

Now that you have your Python file, it’s time to open the terminal. The steps vary slightly depending on your operating system:

  • Windows: Press Windows + R, type cmd, and hit Enter. Alternatively, search for “Command Prompt” or use Windows Terminal.
  • macOS: Press Command + Space, type “Terminal”, and press Enter.
  • Linux: Press Ctrl + Alt + T or open your application launcher and search for “Terminal”.

A black or white terminal window should appear, ready to receive your commands.

4. Navigate to the Script’s Directory

To execute your Python file, you need to change the terminal’s current directory to where your script is saved. Suppose your hello.py file is saved on your desktop; here’s how to navigate there:

  • Windows: cd Desktop
  • macOS/Linux: cd ~/Desktop

You can always check your current directory using the pwd command on macOS/Linux or cd on Windows.

If your file is in a nested folder structure, use the correct path. For example:

cd Documents/PythonProjects/HelloWorld

5. Execute the Python File

You’re now in the right directory. You can run your Python script using one of the following commands:

  • Windows/macOS/Linux (depending on install):
    • python hello.py
    • or
    • python3 hello.py

If everything is working correctly, you should see the following output in your terminal:

Hello, world!

If you see an error like command not found or 'python' is not recognized, it means Python is not properly installed or not added to your system’s PATH.

6. Making Python Files Executable (Optional)

If you are using macOS or Linux, you can make your Python files directly executable by doing the following:

  1. Add a shebang line at the top of the Python file:
#!/usr/bin/env python3
  1. Use the chmod command to make it executable:
chmod +x hello.py
  1. Now you can run it simply by typing: 
    ./hello.py

This is particularly useful for automation scripts or for running applications without repeatedly typing “python” or “python3”.

7. Using Absolute and Relative Paths

In more complex environments, you may want to run Python files that are not in your current directory. You can either use:

  • Relative paths: python ../scripts/hello.py
  • Absolute paths: python /Users/yourname/Documents/scripts/hello.py

Understanding path referencing is crucial when working with large-scale projects or when scheduling scripts with task automation tools such as cron or Windows Task Scheduler.

8. Running Python Files with Arguments

Python scripts often require command-line arguments. Here’s how that works:

# script.py
import sys
print("You passed:", sys.argv[1])

Run it using:

python script.py hello

Expected output:

You passed: hello

Here, sys.argv is a list that stores command-line arguments passed to the script. This is useful when you need to process user-defined input without modifying the script itself.

9. Troubleshooting Common Errors

  • ‘python’ is not recognized: Ensure Python is added to your system’s PATH variable. On installation (especially on Windows), check the box that says “Add Python to PATH”.
  • Syntax Error: Check for missing colons, indentation issues, or misspelled keywords in your Python script.
  • Permission Denied (macOS/Linux): Make sure the file is executable by using the chmod command.
  • Wrong Python Version: If your script requires Python 3.x and you’re accidentally using 2.x, explicitly run python3.

Testing your script in a virtual environment can also help isolate issues caused by conflicting dependencies or multiple Python versions.

10. Best Practices

  • Use Virtual Environments: Manage project dependencies with venv or pipenv.
  • Use Meaningful Filenames: Descriptive names like data_parser.py are easier to locate and maintain.
  • Log Outputs: Redirect terminal output to log files for later diagnosis: python script.py > output.log
  • Use IDEs for Complex Projects: While terminal execution is essential, combining it with robust IDE