Ghostscript Python Interface

Common errors

• ModuleNotFoundError: No module named 'ghostscript'

  cause The Python `ghostscript` package has not been installed in the current environment.
  fix Run `pip install ghostscript` in your activated Python environment. If using Anaconda, you might also consider `conda install -c conda-forge ghostscript` followed by `pip install ghostscript` to ensure proper linkage to the C library.

• RuntimeError: Can not find Ghostscript library (libgs)

  cause The Python `ghostscript` wrapper cannot locate the underlying Ghostscript C library on your system. This often happens if the C library is not installed, or its installation path is not included in the system's PATH environment variable, or if the 32-bit/64-bit architecture mismatch.
  fix 1. Ensure the Ghostscript C library is installed for your OS (e.g., from ghostscript.com). 2. Add the Ghostscript `bin` and `lib` directories to your system's PATH environment variable. 3. On Windows, ensure you've installed the correct 32-bit or 64-bit version of Ghostscript matching your Python installation. 4. You can explicitly set the `GSAPI_LIB` or `GSAPI_LIBDIR` environment variables to point to the Ghostscript shared library.

• subprocess.CalledProcessError: Command '['gs', ...]` or 'No such file or directory: 'gs''

  cause This error, often seen when using the Python `subprocess` module to call Ghostscript, indicates that the `gs` executable (or `gswin64c.exe`/`gswin32c.exe` on Windows) is not found in the system's PATH, or the arguments passed to it are incorrect.
  fix 1. Verify that the Ghostscript executable (`gs` or `gswin*c.exe`) is in your system's PATH. 2. Double-check the arguments passed to the Ghostscript command for typos or incorrect syntax. 3. Consider using the `ghostscript` Python package's high-level API directly to abstract away subprocess management.

• Ghostscript error: **** Could not open the file '"/path/to/output.pdf"'.

  cause This specific error often arises when the output file path passed to Ghostscript arguments is incorrectly quoted, resulting in Ghostscript trying to open a filename that includes literal quotation marks.
  fix Ensure that your Python script does not add extra quotes around the output file path when constructing the argument list for Ghostscript. For example, use `'-sOutputFile=' + output_path` instead of `'-sOutputFile="' + output_path + '"'`.

Warnings

• breaking The `Ghostscript()` constructor in version 0.7 and later no longer accepts arbitrary keyword arguments. Only specific, documented arguments like `stdin`, `stdout`, `stderr` are allowed.
  Fix: Review your `Ghostscript()` calls and remove any unrecognised keyword arguments. Pass Ghostscript-specific options as positional arguments in a list, as done in command-line usage.
• breaking As of `python-ghostscript` version 0.7, support for Python 2.7, 3.4, and 3.5 has been dropped. The minimum required Python version is now 3.6.
  Fix: Upgrade your Python environment to version 3.6 or higher.
• gotcha The Python `ghostscript` package is a wrapper for the external Ghostscript C library. You must install the actual Ghostscript program separately on your system, and its executable/libraries must be discoverable via your system's PATH environment variable (or `GSAPI_LIB`/`GSAPI_LIBDIR` environment variables for direct library path specification).
  Fix: Download and install Ghostscript from its official website (ghostscript.com/download.html) for your operating system. Ensure the installation directory's `bin` and `lib` folders are added to your system's PATH, or set `GSAPI_LIB` to the exact path of the Ghostscript shared library or `GSAPI_LIBDIR` to its directory.
• gotcha When passing document content or arguments to Ghostscript, especially for `run_string`, ensure that `bytes` objects are used. Passing Python `str` objects may lead to encoding issues or unexpected behavior, particularly for non-ASCII characters, although the high-level interface attempts to handle string encoding.
  Fix: Explicitly encode Python strings to bytes using a suitable encoding (e.g., `text.encode('utf-8')` or `locale.getpreferredencoding()`) before passing them to Ghostscript functions that expect binary data.
• gotcha When specifying output file paths in Ghostscript arguments, particularly on Windows, use raw strings (e.g., `r'C:\path\file.pdf'`) or forward slashes (`'C:/path/file.pdf'`) to avoid issues with backslash escape sequences. Additionally, if generating multiple output files (e.g., pages to images), include `%d` in the output filename (e.g., `-sOutputFile=page_%d.png`).
  Fix: Always use raw strings or forward slashes for paths. For multi-page output, ensure the output filename contains `%d` to generate sequential files for each page. Avoid double-quoting output file parameters, as this can break Ghostscript processing.

Install

• pip install ghostscript Install from PyPI

Imports

• ghostscript

  import ghostscript

• Ghostscript

  from ghostscript import Ghostscript

  This is the high-level interface class.
• gsapi

  import gsapi

  Used for the low-level C-API bindings, often found in the Ghostscript C library's own Python demos.

Quickstart

This quickstart demonstrates two common uses of the `ghostscript` library: converting an existing PostScript file to PDF, and processing a PostScript string directly into a PDF. It utilizes the high-level `Ghostscript` class to manage the Ghostscript interpreter instance and pass arguments. Note that the Ghostscript C library must be installed and accessible by the Python wrapper for these examples to run.

import sys
import locale
import ghostscript

# Example 1: Convert a PostScript file to PDF using the high-level interface
# This assumes 'input.ps' exists and you want 'output.pdf'
# Ensure Ghostscript C library is installed and in PATH.
# For Windows, you might need to specify the GS DLL path via GSAPI_LIB or GSAPI_LIBDIR env var.

# Simulate command-line arguments for Ghostscript
args_ps2pdf = [
    "ps2pdf", # actual value doesn't matter for the python wrapper, but typically 'gs'
    "-dNOPAUSE",
    "-dBATCH",
    "-dSAFER",
    "-sDEVICE=pdfwrite",
    "-sOutputFile=output.pdf",
    "-f",
    "input.ps"
]

try:
    # Ghostscript expects arguments to be byte strings in some contexts
    # For the high-level interface, strings are often handled, but explicit encoding can be safer
    encoded_args = [arg.encode(locale.getpreferredencoding()) for arg in args_ps2pdf]
    ghostscript.Ghostscript(*encoded_args)
    print("Converted input.ps to output.pdf")
except ghostscript.GhostscriptError as e:
    print(f"Ghostscript error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# Example 2: Process a string document directly
# Documents passed to ghostscript need to be bytes
doc_content = b"""%!PS
/Helvetica findfont 20 scalefont setfont
50 50 moveto (Hello World from Python) show
showpage quit
"""

args_string_to_pdf = (
    "-dNOPAUSE",
    "-dBATCH",
    "-dSAFER",
    "-sDEVICE=pdfwrite",
    "-sOutputFile=hello_world.pdf",
    "-" # '-' indicates input from stdin
)

try:
    with ghostscript.Ghostscript(*args_string_to_pdf) as gs:
        gs.run_string(doc_content)
    print("Generated hello_world.pdf from string content")
except ghostscript.GhostscriptError as e:
    print(f"Ghostscript error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")