How to use PStill on the command line

This document refers to PStill version 1.84 and better but its general content may be useful also for earlier releases, however their option set may be more limited.

For the impatient:

pstill -M defaultall -o output.pdf input

should work for most users. '-M defaultall' is a meta options for a basic setup with page size take over, compression, transparency handling, unicode map and font reprocessing.

To concat PDF using the 'pdfasm' tool (part of PStill starting 1.84.32):

pdfasm output.pdf input1.pdf input2.pdf input3.pdf ...

While PStill can also combine PDF, pdfass avoids the reprocessing step and is much faster in general.

To linearize PDF using the 'pdflin' tool (part of PStill starting 1.84.32):

pdflin -linearize [-compressxrefs] output.pdf input.pdf

Creates a web-optimized version of the source.

'PStill', 'pstill' and 'GPStill' - what is the difference?

'PStill' is the name for the general software and engine, 'pstill' is the name of the command line converter module, while 'GPStill' is the name of the GUI PStill version available currently for Windows systems. This document handles the use of 'pstill', the command line program. For GPStill see 'PStill_Guide.pdf' as part of the PStill/Win distribution.

Is there a difference in usage of 'pstill' on Windows, Linux and other *NIX OS?

No, all versions accept the very same set of options.

How can I get a list of options?

Run pstill -H, since the option list may be long you can also pipe it into a file, e.g. pstill -H | more or pstill -H > options.txt and open this file with an editor of your choice.

Note: Options are case sensitive! E.g. -m is different to -M !

Are there limitations for unlicensed versions?

Since the Linux and *NIX versions are free (as free beer) for personal and edu use no restrictions except a one second pause and a console message upon startup applies for them. The Windows command line version however needs licensing, otherwise it will place a visual mark on its output and a long pause of 15 seconds is in effect before a conversion is started.

Can I run several pstill processes in parallel on the same machine?

Yes, as long you give each PStill a unique temporary directory using option -T path, otherwise the processes may interfere. Also keep in mind that PStill is licensed by running 'instance', so you may need more licenses or a special 'parallel' license for this kind of use in a commercial environment.


IMPORTANT: Install correctly before use!

PStill needs installation, usually it is just a matter of supplying the base fonts and make them known to PStill. However this step is important, if you omit it or use bad fonts here the results may be not what you expect.

On UNIX systems read 'INSTALL' (contained in the PStill distribution) before using PStill on your data, on Windows first run GPStill and let it generate a base font set. If you look for base fonts see also http://www.pstill.com in section 'Other PStill and PDF related information' and the PStill FAQ.

PStill needs to know where its helper files are: You may either set the environment variable PSTILL_PATH to the value of the PStill program directory or call 'pstill' with an absolute path to the executable, e.g.: "C:\program files(x86)\gpstill\pstill.exe" ...

Also keep in mind that PStill chdirs to its program directory during operation, so when supplying file paths make them relative to this directory or supply absolute paths too.


Basic usage for 'office use'

Office use is defined by relative low requirements for the resulting PDF in terms of color space accuracy and placement. The main goal here is to provide 'screen' and 'laser printer' accurate output creating small files.

To convert a file to PDF use this option set:

pstill -F a4 -2 -c -c -c -c -g -i -p -t -v -J 75 -C -K -M regenfonts -M optimizefonts -W -M useSrcUnicodeMap -o outputfile.pdf inputfile

Options in detail:

  • -F a4 set the default page size to A4, you may want to use other formats here (letter, a3, legal, etc.). If not specified the default is US letter
  • -2 turns on PS Language Level 2 processing, recommended
  • -c turns on Flate compression of the output, the more '-c' the better
  • -g advises PStill to get the page size for the job, if possible
    Note: Use the -F format or -w # / -h # options to specify a large enough default page as this option can only shrink the default page size.
  • -i advises PStill to include needed fonts
  • -p advises PStill to include fonts as subset
  • -t advises PStill to take color transfer into account, recommended
  • -v turns on verbose output (optional)
  • -J # advises PStill to compress image by JPEG factor # (0-100, 100 best) if possible
  • -C advises PStill to convert the output to RGB
  • -K advises PStill to write fonts in full encoding
  • -M regenfonts advises PStill to regenerate fonts (is able to include more fonts)
  • -M optimizefonts advises PStill to optimize the encoding tables in the output (smaller results)
  • -W advises PStill to perform extra processing for Windows printer driver generated job
  • -M useSrcUnicodeMap advises PStill to reprocess and include CMaps in the result (better text extraction and text search)
  • -o out this sets the output name, the file is created by PStill
  • input this defines the input file(s), multiple input files possible

Attention: If your input contains screenshots or other 'artificial' images, using JPEG (option '-J #') may make the results actually larger in size than necessary! This is not a limitation of PStill but of the the gerneral method and you should not use -J # for such files.


Basic usage for 'prepress use'

Prepress use is defined by the higher placement accuracy of the output and needs usually CMYK/spotcolors colorspace.

pstill -F a4 -2 -c -c -c -c -g -i -t -K -d 700 -a 4 -m XimgAsCMYK -m Xspot -m Xoverprint -M regenfonts -M optimizefonts -W -M useSrcUnicodeMap -o outputfile.pdf input

  • -F a4 set the default page size to A4, use -w # -h # for custom formats instead
  • -2 turns on PS Language Level 2 processing, recommended
  • -c compress using Flate method (lossless)
  • -g advises PStill to get the page size for the job, if possible
  • -i advises PStill to include fonts
  • -t advises PStill to take the transfer function into account
  • -K tells PStill to write fonts fully encoded
  • -d # tells PStill to use an internal raster of 700 DPI (makes for ~1400 dpi placement accuracy)
  • -a # tells PStill to write #+2 digits behind the decimal dot for coordinates
  • -m XimgAsCMYK advises PStill to convert all RGB images to CMYK
  • -m Xspot advises PStill to write spot colors as spots (drop this option if you want spots converted to CMYKs)
  • -m Xoverprint advises PStill to take over 'overprinting'
  • -M regenfonts advises PStill to regenerate fonts (is able to include more fonts)
  • -M optimizefonts advises PStill to optimize the encoding tables in the output (smaller results)
  • -W advises PStill to perform extra processing for Windows printer driver generated job
  • -M useSrcUnicodeMap advises PStill to reprocess and include CMaps in the result (better text extraction and text search)
  • -o out this defines the output file
  • input defining the input, multiple files possible here

    In general PStill allows to define several input files, also in a mixed format of PS, EPS, PDF, TIFF and JPEG. PStill process them in sequence and concat their results in the output.

    Option -K should be used whenever you plan to reprocess the resulting PDFs, e.g. concat them in other tools or submit them to third parties. This way PStill emits more font encoding imformation to the PDF.


    PDF/A output

    PDF/A is a subset and more focused form of PDF for the purpose of long term archiving. PStill can output PDF/A-1b:

    pstill -M defaultall -m XPDFA=INTENTNAME -m XICCProfile=COLORPROFILE.ICC -m XPDFACompat=9 -C -o outputfile.pdf input

  • -M defaultall sets reasonable defaults, incl. transparency flattening
  • -m XPDFA=INTENTNAME defines the output condition name
  • -m XICCProfile=COLORPROFILE.ICC defines the ICC color profile that matches the output condtion
  • -m XPDFACompat=# make output compatible to Acrobat 7, 8 or 9 preflight (use 9 for best PDF/A compatibility). Option available in 1.72.20 and newer.
  • -C convert output to RGB (use only when your condition is also RGB)

    • Return to main page

    This information is given in the hope to be useful but without any warranties. Trademarks are used only for identification purposes. 'PStill' is a registered trademark of Frank Siegert. Acrobat and others are registered trademarks of Adobe Inc. and are used for identification purposes only. Please send questions or fixes to my email address (See contact info on the main page)

    Data Protection Statement / Datenschutzerklärung