Preview Pango text as an image with pango-view

You will render a string or text file with pango-view, save the result as a PNG, and check the file without opening a graphical window. The examples use the Ubuntu package pango1.0-tools, version 1.52.1, installed on the reference machine. Allow about ten minutes for a first preview, or less once the font and layout choices are known.

Everything here is an ordinary user operation. You do not need sudo to render text in a directory you can write to. Keep the input and output paths separate while experimenting, because --output can replace an existing file.

1. Check the installed command

Confirm which executable the shell will run, then record its version. The version matters because this guide describes the options and defaults from the installed Pango release, not an abstract interface shared by every distribution.

$ command -v pango-view
/usr/bin/pango-view
$ pango-view --version
pango-view (pango) 1.52.1

Your version and path may differ. If the command is missing, install the distribution package that provides pango-view through your normal package-management process, then repeat this check. Do not copy a package name from another distribution without checking its package index.

2. Render a short string to a PNG

Use --text when the input fits comfortably in the shell command. --no-display tells the program not to show the result in a window, while --output writes the rendered image to a file. The default backend is Cairo.

$ pango-view --no-display \
    --text='Pango preview' \
    --output=/tmp/pango-preview.png
$ file /tmp/pango-preview.png
/tmp/pango-preview.png: PNG image data, 139 x 39, 8-bit/color RGB, non-interlaced

The exact dimensions depend on the installed font configuration and Pango settings, so do not treat 139 x 39 as a required result. The useful checks are a zero exit status and a PNG file at the requested path. If you need to retain an earlier preview, choose a new filename first. Avoid using > for this operation: pango-view already has an output option, and standard output is not the documented image destination here.

3. Render a text file

The normal file form is the command followed by the input file. The manual shows the syntax as pango-view [OPTION?] - FILE; the hyphen separates options from the file argument. This example creates a small input without changing any system file.

$ printf 'Pango & layout\nSecond line\n' > /tmp/pango-sample.txt
$ pango-view --no-display \
    --output=/tmp/pango-file.png \
    -- /tmp/pango-sample.txt
$ file /tmp/pango-file.png
/tmp/pango-file.png: PNG image data, 144 x 58, 8-bit/color RGB, non-interlaced

Use -- when the input path might begin with a hyphen or when you want the option boundary to be obvious. The source file is read, not rewritten. If it contains characters meaningful to Pango markup, leave --markup off unless you deliberately want those characters interpreted.

4. Choose a font and wrap long text

Set a font description with --font. To wrap text, supply a width and a wrap mode together. Width is measured in points by default, and --wrap=word wraps at word boundaries. The manual says that a wrap mode needs a width; without both settings, you are not asking for the same layout.

$ pango-view --no-display \
    --font='DejaVu Sans 18' \
    --width=240 \
    --wrap=word \
    --text='A longer sentence that wraps at the requested width.' \
    --output=/tmp/pango-wrapped.png
$ file /tmp/pango-wrapped.png
/tmp/pango-wrapped.png: PNG image data, 340 x 107, 8-bit/color RGB, non-interlaced

These dimensions are an observed result from the reference machine, not a promise for another font installation. If the chosen font is unavailable, Pango may fall back to another font. Check the image visually, or use file and a trusted image viewer, before treating the preview as a final asset.

5. Use markup only for intentional formatting

Add --markup when the text is Pango markup rather than literal plain text. This lets you exercise attributes such as a foreground colour or bold weight. Markup is input data, not a general-purpose HTML document, so start with a small known-good fragment.

$ pango-view --no-display --markup \
    --text='<span foreground="#0057b8" weight="bold">Blue heading</span>' \
    --output=/tmp/pango-markup.png
$ file /tmp/pango-markup.png
/tmp/pango-markup.png: PNG image data, 140 x 40, 8-bit/color RGB, non-interlaced

Without --markup, the angle brackets are treated as text. With it, malformed or untrusted input can change the appearance of the rendered output. Do not pass arbitrary user content through a markup template unless you escape or otherwise constrain it first. The command renders an image; it does not make the input safe for another HTML or XML consumer.

6. Adjust output deliberately

Use --background and --foreground for colours, --align for left, centre or right alignment, and --margin for CSS-style pixel margins. The defaults are easy to misread: text layout uses points unless --pixels is selected, while the margin option is described in pixels. Keep those units in mind when comparing previews.

Use --height=+points for a positive point height, or a negative value to express a number of lines for ellipsising. Use --ellipsize=start, middle or end when clipped text should show an ellipsis. These options are useful for testing a fixed UI region, but they do not enlarge a narrow width. Set --width as well when width is part of the constraint.

$ pango-view --no-display \
    --font='DejaVu Sans 16' \
    --width=320 \
    --height=-2 \
    --ellipsize=end \
    --background='#ffffff' \
    --foreground='#202020' \
    --margin='12 16' \
    --text='This preview is limited to two lines.' \
    --output=/tmp/pango-constrained.png
$ file /tmp/pango-constrained.png

If a setting is unclear, run pango-view --help or consult the installed pango-view(1) manual. --help-cairo exposes the separate Cairo annotation option, including baselines, layouts and glyphs, which is useful when debugging text positioning rather than producing a polished preview.

7. Diagnose failures without overwriting useful work

A missing output usually means the command failed before rendering. Check the input path and destination permissions without changing them:

$ test -r /path/to/input.txt && echo 'input is readable'
$ test -w /path/to/output-directory && echo 'output directory is writable'
$ pango-view --no-display --text='test' --output=/tmp/pango-test.png
$ printf 'exit status: %s\n' "$?"
exit status: 0

If you used a file, verify the source path after the command has failed. If the image is unexpectedly narrow or clipped, inspect --width, --wrap, --height and --ellipsize as a group. If text looks different between machines, compare pango-view --version, the selected font, the backend and the available fonts. A successful exit status confirms that rendering completed; it does not prove that the chosen font or visual layout matches your intention.

For a replace-in-place workflow, render to a new name and rename only after checking it:

$ pango-view --no-display --text='New version' --output=/tmp/preview.png.new
$ file /tmp/preview.png.new
$ mv /tmp/preview.png.new /tmp/preview.png

The final mv changes the destination. If the new render fails, leave the existing file alone and remove only the incomplete temporary file after checking its path. Do not use a broad wildcard for cleanup.