How to Run FontForge Python Scripts from the Command Line

This guide explains how to execute FontForge Python scripts directly from your terminal or command prompt. Running scripts via the command-line interface (CLI) allows you to automate font conversions, glyph modifications, and metric adjustments in a headless environment. You can achieve this using the native fontforge command with the script flag, using the bundled ffpython interpreter, or by importing FontForge into your standard system Python environment.

Method 1: Using the fontforge -script Flag

The most common and cross-platform way to run a FontForge Python script is by invoking the main fontforge binary with the -script argument.

fontforge -script your_script.py

FontForge automatically detects Python based on the .py file extension. If your script uses a custom extension or you want to explicitly enforce the Python engine, add the -lang=py flag:

fontforge -lang=py -script your_script.txt

Method 2: Using the ffpython Interpreter

Many FontForge packages (notably on macOS via Homebrew and on Windows through the official installer) include a standalone executable named ffpython. This is a Python interpreter pre-configured with the FontForge module already in its path.

To run your script with ffpython, execute:

ffpython your_script.py

You can also use this environment interactively by simply running ffpython without arguments to open an interactive REPL.

Method 3: Using the System Python Interpreter

If you have installed FontForge using a package manager that configures system-wide Python bindings (such as python3-fontforge on Debian/Ubuntu), you can run your script directly using your standard Python interpreter.

Ensure your script begins by importing the module:

import fontforge

# Open an existing font
font = fontforge.open("font.ttf")
print(f"Loaded font: {font.fontname}")
font.close()

Then, run the script normally:

python3 your_script.py

Passing Command-Line Arguments

When passing arguments to your script using fontforge -script, any parameters placed after the script filename are passed directly to Python's sys.argv.

Run the command:

fontforge -script your_script.py input.ttf output.woff

Access the arguments in your Python file:

import sys
import fontforge

if len(sys.argv) < 3:
    print("Usage: fontforge -script script.py <input> <output>")
    sys.exit(1)

input_file = sys.argv[1]
output_file = sys.argv[2]

font = fontforge.open(input_file)
font.generate(output_file)
font.close()

Suppressing UI and GUI Warnings

When executing FontForge via the CLI on Linux servers without a desktop environment, you might encounter warnings regarding the X display. FontForge runs automatically without a GUI when passed the -script flag, but you can prevent X-related startup checks by running it in a headless context or unset the DISPLAY environment variable if needed:

DISPLAY="" fontforge -script your_script.py