Skip to main content

How to Check Python Syntax Without Execution

Verifying the syntax of your Python code without running it is a vital step in development, catching errors early and preventing runtime issues.

This guide explores various techniques for static syntax checking, including using the built-in py_compile and compileall modules, custom scripts with ast, and external tools like pyflakes and pylint.

Checking Syntax with py_compile​

The py_compile module compiles a Python source file to bytecode, which also checks for syntax errors:

python -m py_compile main.py
# OR
python3 -m py_compile main.py
  • python -m py_compile: This runs the py_compile module as a script. The -m flag tells Python to locate py_compile within the Python library and run it.
  • main.py: Replace this with the actual name of your Python file.
  • If no error messages are printed the Python code is valid, otherwise you will receive the output detailing the line number, and type of error.

Checking Syntax with compileall​

The compileall module is useful for checking the syntax of all Python files within a directory (and its subdirectories):

python -m compileall -q .
# OR
python3 -m compileall -q .
  • python -m compileall: Runs the compileall module, which compiles all .py files in the given directory.
  • -q: This is the "quiet" flag. It suppresses the output of filenames during compilation. Without -q, you'll see a list of every file compiled.
  • .: This refers to the current directory. You can replace this with a specific directory path.

Checking Syntax with a Custom Script Using ast​

For more control over the syntax checking process (and to integrate it into your own scripts), use the ast (Abstract Syntax Trees) module:

# check_syntax.py
import ast
import traceback
import sys 

def check_syntax(file_name):
    try:
        with open(file_name, 'r', encoding='utf-8') as file:
            source = file.read()
        ast.parse(source)  # Attempt to parse the source code
        print(f"Valid syntax: {file_name}")
        return True
    except SyntaxError:
        traceback.print_exc()  # Print detailed error information
        print(f"Invalid syntax: {file_name}")
        return False
    except Exception as e:  # Catch other potential errors (like file not found)
        print(f"An unexpected error occurred: {e}")
        return False

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python check_syntax.py <file1.py> [file2.py ...]")
        sys.exit(1)

    all_valid = True
    for file_name in sys.argv[1:]:  # Iterate through provided file names
        if not check_syntax(file_name):
            all_valid = False

    if not all_valid:
        sys.exit(1) # Non-zero exit code on error

  • The code reads the entire file and attempts to parse it using ast.parse().

  • This is a standalone script (check_syntax.py). You run it from the command line, passing the Python files you want to check as arguments:

    python check_syntax.py main.py another.py
    python3 check_syntax.py main.py another.py

  • Error Handling: The try...except block catches SyntaxError (for syntax issues) and other potential exceptions (like FileNotFoundError).

  • Detailed Error Output: traceback.print_exc() provides detailed error information, including the line number and error message.

  • Command Line Usage: The script now accepts file names as command-line arguments, making it reusable.

  • Exit Codes: The script now returns a non-zero exit code (1) if any of the files have invalid syntax. This is crucial for integration into build scripts and CI/CD pipelines. A zero exit code indicates success (all files are syntactically valid).

Checking Syntax with pyflakes​

pyflakes is a popular tool that checks for syntax errors and some common logical errors (like unused imports):

pip install pyflakes  # Install if you don't have it
pip3 install pyflakes
pyflakes main.py
  • If there are no errors or warnings in the file, pyflakes will produce no output.

Checking Syntax with Pylint​

Pylint is a powerful static analysis tool that goes far beyond simple syntax checking. It checks for style issues, potential bugs, and much more. It's more comprehensive than pyflakes.

pip install pylint
pip3 install pylint
pylint main.py
  • Pylint will output a lot of information, including style recommendations, potential errors, and a code quality score. It's generally used for more than just syntax checking.

Conclusion​

This guide described several methods for checking the syntax of Python scripts without executing them.

  • For basic syntax checking, py_compile and compileall are built-in and convenient.
  • For more in-depth checks (including potential logical errors), pyflakes is an excellent choice.
  • For comprehensive code analysis, pylint offers a very wide range of checks.
  • Using these tools can greatly improve your development workflow and help prevent runtime errors.

The custom ast script is highly recommended for flexible, scriptable syntax checks.

Table of Contents