A modern, open-source PostScript interpreter written in Python.
PostForge is a complete PostScript interpreter that faithfully implements the PostScript Level 2 specification while adding selected Level 3 enhancements. It reads PostScript files and produces PNG images, PDF documents, SVG files, TIFF images, or renders them in an interactive Qt display window.
PostForge is designed as an open-source alternative to GhostScript for use cases where Python integration, transparency, and debuggability matter more than raw speed. Its modular architecture makes it well suited for education, PostScript development, and embedding in Python workflows.
The interpreter covers the full Level 2 specification and includes PDF font embedding/subsetting, ICC color management, and a Cython-accelerated execution loop.
 |
 |
 |
 |
 |
 |
See the sample gallery for larger rendered examples.
- Full Level 2 Implementation — Strict Level 2 compatibility with selected Level 3 enhancements that don't break Level 2 programs
- Interactive Executive Mode — Built-in PostScript command line for live exploration, debugging, and experimentation
- Cython-Accelerated Execution — Optional Cython-compiled execution loop providing 15–40% speedup depending on workload
- Multiple Output Formats — PNG, PDF, SVG, and TIFF output via Cairo graphics backend, plus an interactive Qt display window with a PostScript command prompt; TIFF supports multi-page and CMYK output for prepress workflows; extensible architecture makes it straightforward to add new devices
- PDF Font Embedding — Type 1 font reconstruction and subsetting, TrueType/CID font extraction with CIDToGIDMap and ToUnicode support
- EPS Support — Automatic page cropping to EPS content dimensions with HiResBoundingBox precision; handles DOS EPS binary format
- ICC Color Management — sRGB, CMYK, and Gray ICC profiles via lcms2, with tiered fallback for color accuracy
- PostScript-Based Test Suite — 2,500+ unit tests written in PostScript, using a custom assertion framework that tests the interpreter from the language level
- Memory Analysis Tools — Built-in profiling, garbage collection analysis, and leak detection for debugging and optimization
git clone https://github.com/AndyCappDev/postforge.git
cd postforge
./install.shThe install script checks for Python 3.13+ and Cairo, creates a virtual
environment, installs all dependencies, builds the optional Cython
accelerator, and installs the pf command system-wide via /usr/local/bin.
If anything is missing, it will tell you which package to install for your
distribution (Debian/Ubuntu, Fedora, RHEL/CentOS, Arch, openSUSE).
For the Cython-accelerated execution loop (15–40% speedup), a C compiler
is needed. Install it before running ./install.sh:
| Distribution | Command |
|---|---|
| Debian/Ubuntu | sudo apt install build-essential |
| Fedora | sudo dnf install gcc |
| Arch | sudo pacman -S base-devel |
| RHEL/CentOS | sudo yum install gcc |
| openSUSE | sudo zypper install gcc |
PostForge works without a C compiler — the install script will skip the Cython build and use a pure Python fallback.
git clone https://github.com/AndyCappDev/postforge.git
cd postforge
./install.shRequires Homebrew. The install script will check for Python 3.13+ and Cairo, and tell you what to install if anything is missing.
Installing Cairo via Homebrew requires Xcode Command Line Tools
(xcode-select --install), which also provides the C compiler needed for
the Cython-accelerated execution loop (15–40% speedup). Both are built
automatically by the install script.
git clone https://github.com/AndyCappDev/postforge.git
cd postforge
install.batThe install script checks for Python 3.13+, creates a virtual environment,
installs all dependencies, builds the optional Cython accelerator, and adds
PostForge to your PATH so the pf command works from any terminal. Open a
new terminal after installation for the PATH change to take effect.
Prerequisites: Install Python 3.13+ and check "Add Python to PATH" during installation. Cairo is bundled with the pycairo package on Windows — no separate install needed.
For the Cython-accelerated execution loop (15–40% speedup), install Microsoft C++ Build Tools and select the "Desktop development with C++" workload. PostForge works without them — the install script will skip the Cython build and use a pure Python fallback.
# Interactive PostScript prompt
pf
# Render to the Qt display window
pf samples/tiger.ps
# Save as PNG → pf_output/tiger-0001.png
pf -d png samples/tiger.ps
# Save as PDF → pf_output/tiger-0001.pdf
pf -d pdf samples/tiger.ps
# Save as SVG → pf_output/tiger-0001.svg
pf -d svg samples/tiger.ps
# Save as TIFF → pf_output/tiger-0001.tif
pf -d tiff samples/tiger.ps
# Multi-page TIFF → pf_output/document.tif
pf -d tiff --multipage-tiff document.ps
# CMYK TIFF for prepress → pf_output/tiger-0001.tif
pf -d tiff --cmyk samples/tiger.ps
# Render an EPS file (auto-crops to content)
pf -d png samples/fancy.eps
# Custom output path → renders/result-0001.png
pf -o result.png --output-dir renders samples/tiger.ps
# Render only specific pages from a multi-page document
pf -d pdf --pages 1-3,7 document.ps
# SVG with text rendered as path outlines instead of <text> elements
pf --text-as-paths -d svg samples/test1.ps
# Pipe PostScript from stdin
cat document.ps | pf -d png -For complete command line options, see the User Guide.
To update PostForge to the latest version:
cd postforge
git pull
./install.sh # Linux/macOS
install.bat # WindowsThe install script will update dependencies and rebuild the Cython accelerator as needed. Your configuration and font cache are preserved.
Linux/macOS:
./uninstall.shRemoves the system commands (pf, postforge), virtual environment, font
cache, and build artifacts. The source code is left in place.
Windows:
uninstall.batRemoves PostForge from your PATH, the virtual environment, font cache, and build artifacts. Open a new terminal after uninstalling for the PATH change to take effect.
PostForge and GhostScript serve different needs:
| PostForge | GhostScript | |
|---|---|---|
| Language | Python | C |
| Architecture | Open, modular, readable | Monolithic, optimized for speed |
| Best for | Debugging, education, Python integration, development | Production rendering, printer drivers, full Level 3 |
| Speed | Interpreted (with optional Cython) | Fast native execution |
| PostScript Level | Level 2 complete, selected Level 3 | Full Level 3 |
| License | AGPL-3.0 | AGPL-3.0 |
Choose PostForge when you want to understand what a PostScript program is doing, embed an interpreter in a Python application, develop or debug PostScript code, or learn how PostScript works.
Choose GhostScript when you need maximum rendering speed, full Level 3 compliance, printer support, or a battle-tested production tool.
That said, don't be fooled by "written in Python" — PostForge is a serious interpreter with full Level 2 compliance, 2,500+ unit tests, and production-quality output. It handles complex real-world PostScript files and is plenty fast for most rendering tasks.
- User Guide — Installation, CLI usage, output options
- Contributing Guide — Setup, conventions, and PR workflow
- Architecture Overview — How PostForge works internally
- Implementing Operators — Adding new PostScript operators
- Testing Guide — Writing and running PostScript-based tests
- Visual Regression Testing — PNG, PDF, SVG, and TIFF visual comparison
- Adding Output Devices — Creating new output backends
- Profiling — Performance and memory analysis
- Level 2 Compliance Assessment
- Detailed Gap Analysis
- Sample Gallery
- Background — Author history and how PostForge came to be
PostForge welcomes contributions. See the Contributing Guide for setup instructions, code conventions, and PR workflow.
For a quick start:
- Clone the repository and run
./install.sh(orinstall.baton Windows) - Read the Architecture Overview to understand the codebase
- Check the Operator Implementation Guide for coding standards
- Run the test suite with
pf unit_tests/ps_tests.psto verify your changes
- Python 3.13+
- Cairo graphics library (system package on Linux/macOS; bundled with pycairo on Windows)
- Core Python packages: pycairo, psutil, jpeglib, Pillow, pypdf
- Optional: PySide6 (for the interactive Qt display)
Copyright (c) 2025-2026 Scott Bowman
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See LICENSE.txt for the full license text.