XDVIPSK(1) General Commands Manual XDVIPSK(1)

xdvipsk - convert a TeX DVI file to PostScript (dvips extexsion)

xdvipsk [OPTIONS] file[.dvi]

xdvipsk has a few base extensions:

allows flexible inclusion of bitmap images. xdvipsk accepts BMP, PCX, TIFF, JPEG, PNG formats and is able to perform the same actions as with EPS images: scaling, rotating, trim, viewport.

xdvispk.def (extended `dvips.def`) driver for graphics package does not yet implement the operations of clipping, trimming and viewport.

adds OpenType font support. Map files with information about OpenType fonts used in .dvi files are produced by LaTeX package luafontmaps.

PostScript header file texcid.pro is used for inclusion of OpenType fonts in PostScript files. It is an analogue of texps.pro that is used in case of Type1 fonts.

accepts font map special commands with prefixes mapfile and mapline to supplement font mapping provided in psfonts.map tables. mapfile is used for reading a font map file consisting of one or more font map lines. The name of the map file is given together with an optional leading modifier character (+). There is a companion special type mapline that allows to scan single map lines; its map line argument has the same syntax as the map lines from a map file.

Both specials can be used concurrently. The operation mode is selected by an optional modifier character (+) in front. This modifier defines how the individual map lines are going to be handled, and how a collision between an already registered map entry and a newer one is resolved; either ignoring a later entry with a warning in case modifier charcter is given, or replacing an existing entry in case no modifier character is given.

adds Lua callbacks for specials (prescan, scan), after prescan, drawchar, drawrule, stack, dvips exit.

xdvipsk reads Lua script file xdvipsk.lua if it is found by `kpse` and looks for these Lua functions:

prescan_specials_callback(special, table) special- original special data, table with keys: `hh`, `vv`, `pagenum`.

scan_specials_callback(special, table) special- original special data, table with keys: `hh`, `vv`, `pagenum`

after_prescan_callback(table) table with keys: `hpapersize`, `vpapersize`, `hoff`, `voff`, `actualdpi`, `vactualdpi`, `num`, `den`, `mag`, `totalpages`

after_drawchar_callback(table) table with keys: `charcode`, `cid`, `pixelwidth`, `rhh`, `rvv`, `dir`, `lastfont`, `tounicode`

after_drawrule_callback(table) table with keys: `hh`, `vv`, `dir`, `rw`, `rh`

process_stack_callback(table) table with keys: `cmd`, `hh`, `vv`, `dir`

dvips_exit_callback(table) table with keys: `exitcode`, `log_records_count`

Return values for specials defines processing behaviour:

- non empty string defines modified `dvi special` to be processed;

- true value means processing original `dvi special` in default way;

- empty string | false value means skipping `dvi special`.

Default `Lua` script file can be changed by command line argument -lua or command luascript in xdvipsk config files.

ToUnicode CMaps support through adding GlyphNames2Unicode dictionary to T1 and OpenType fonts.

GlyphNames2Unicode is an undocumented dictionary which Adobe PostScript printer driver uses to communicate with Adobe Distiller. In this dictionary the keys are glyph names, the values are Unicode UTF-16 codes of them. The dictionary is stored in the FontInfo dictionary under the key GlyphNames2Unicode. Ghostscript recognises it and uses to generate `ToUnicode CMaps` with `pdfwrite`.

A bit OBSOLETE info can be found at https://tug.org/TUGboat/tb38-2/tb119tolusis.pdf

Development sources: https://github.com/vtex-soft/xdvipsk.git

Extra xdvipsk options are marked with [+].

-
Read additional options from standard input after processing the command line.
Print a usage message and exit.
Print the version number and exit.
Conserve memory by making three passes over the .dvi file instead of two and only loading those characters actually used. Generally only useful on machines with a very limited amount of memory, like some PCs.
Print only the odd pages. This option uses TeX page numbers, not physical page numbers.
Generate num copies of each page, but duplicating the page body rather than using the /#copies PostScript variable. This can be useful in conjunction with a header file setting bop-hook to do color separations or other neat tricks.
Print only the even pages. This option uses TeX page numbers, not physical page numbers.
Turns bitmap font encoding to off, on (no warnings for missing bitmap font encodings), or strict (with warnings for missing bitmap font encodings).
Generate num consecutive copies of every page, i.e., the output is uncollated. This merely sets the builtin PostScript variable /#copies Default is 1. (For collated copies, see the -C option below.)
Create num copies, but collated (by replicating the data in the PostScript file). Slower than the -c option, but easier on the hands, and faster than resubmitting the same PostScript file multiple times.
Set the debug flags, showing what dvips is doing. This will work unless Dvips has been compiled without the 'DEBUG' option (not recommended). *Note Debug options::, for the possible values of num. Use '-d -1' as the first option for maximum output.
Set both the horizontal and vertical resolution to num, given in dpi (dots per inch). This affects the choice of bitmap fonts that are loaded and also the positioning of letters in resident PostScript fonts. Must be between 10 and 10000. This affects both the horizontal and vertical resolution. If a high resolution (something greater than 400 dpi, say) is selected, the -Z flag should probably also be used. If you are using fonts made with Metafont, such as Computer Modern, mktexpk needs to know about the value for num that you use or Metafont will fail. See the modes.mf file (https://ctan.org/pkg/modes) for a list of resolutions and mode names for most devices.
Maximum drift in pixels of each character from its 'true' resolution-independent position on the page. The default value of this parameter is resolution dependent (it is the number of entries in the list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400, 2800, 3200, ...] that are less than or equal to the resolution in dots per inch). Allowing individual characters to 'drift' from their correctly rounded positions by a few pixels, while regaining the true position at the beginning of each new word, improves the spacing of letters in words.
Generate an EPSF file with a tight bounding box. This only looks at marks made by characters and rules, not by any included graphics. In addition, it gets the glyph metrics from the tfm file, so characters that print outside their enclosing tfm box may confuse it. In addition, the bounding box might be a bit too loose if the character glyph has significant left or right side bearings. Nonetheless, this option works well enough for creating small EPSF files for equations or tables or the like. (Of course, dvips output, especially when using bitmap fonts, is resolution-dependent and thus does not make very good EPSF files, especially if the images are to be scaled; use these EPSF files with care.) For multiple page input files, also specify '-i' to get each page as a separate EPSF file; otherwise, all the pages are overlaid in the single output file.
Run as a filter. Read the .dvi file from standard input and write the PostScript to standard output. The standard input must be seekable, so it cannot be a pipe. If you must use a pipe, write a shell script that copies the pipe output to a temporary file and then points dvips at this file. This option also disables the automatic reading of the PRINTER environment variable; use '-P$PRINTER' after the -f to read it anyway. It also turns off the automatic sending of control-D (ASCII code 4) if it was turned on with the -F option or in the configuration file; use -F after the -f to send it anyway.
Write control-D (ASCII code 4) as the very last character of the PostScript file. This is useful when dvips is driving the printer directly instead of working through a spooler, as is common on personal systems. On systems shared by more than one person, this is not recommended.
Shift non-printing characters (ASCII 0-32, 127) to higher-numbered positions. This was useful to work around bugs in old versions of Adobe's PDF reader. It's more likely to cause problems nowadays.
Prepend name as an additional header file, or, if name is '-', suppress inclusion of default header files. If -h is given multiple times, the headers are included in the order given. Any definitions in the header file get added to the PostScript userdict.
[+]-H
Turbo mode for PS graphics
Make each section be a separate file; a "section" is a part of the document processed independently, most often created to avoid memory overflow. The filenames are created replacing the suffix of the supplied output file name by a three-digit sequence number. This option is most often used in conjunction with the -S option which sets the maximum section length in pages; if -i is specified and -S is not, each page is output as a separate file. For instance, some phototypesetters cannot print more than ten or so consecutive pages before running out of steam; these options can be used to automatically split a book into ten-page sections, each to its own file. On the other hand, if your document uses very large fonts or very large included figures, Dvips might take it upon itself to split the output into unwanted sections, to try to avoid overflowing printer memory.
[+]-I p
Resize mode for emTeX graphics
Download only needed characters from Type 1 fonts. This is the default in the current release. Some debugging flags trace this operation. You can also control partial downloading on a per-font basis, via the psfonts.map file. [+]-J Download OpenType fonts partially.
Print crop marks. This option increases the paper size (which should be specified, either with a paper size special or with the -T option) by a half inch in each dimension. It translates each page by a quarter inch and draws cross-style crop marks. It is mostly useful with typesetters that can set the page size automatically. This works by downloading 'crop.pro'.
This option causes comments in included PostScript graphics, font files, and headers to be removed. This is sometimes necessary to get around bugs in spoolers or PostScript post-processing programs. Specifically, the %%Page comments, when left in, often cause difficulties. Use of this flag can cause some included graphics to fail, since the PostScript header macros from some software packages read portions of the input stream line by line, searching for a particular comment. This option has been turned off by default because PostScript previewers and spoolers have been getting better.
The last page printed will be the first one numbered num Default is the last page in the document. If the num is prefixed by an equals sign, then it (and any argument to the -p option) is treated as a sequence number, rather than a value to compare with \count0 values. Thus, using -l =9 will end with the ninth page of the document, no matter what the pages are actually numbered.

On the other hand, if num is suffixed by .SEQ, the SEQth occurrence of num is used; for example, -l 99.2 says to end processing with the second page numbered 99 in the document.

By default or with -L1, the last 'papersize' special wins; with -L0, the first special wins.
When looking for matching paper sizes, permit rotation of page content on the page to match the given size; the default, as of Dvips 2022.1, is not to do this. It should not be needed in modern systems with normal print spoolers, and can be harmful when converting to PDF (*note Config file paper sizes::). This option accepts an optional suffix of 0 (to explicitly disable) or 1 (to explicitly enable); if the option is specified without a suffix, it enables the behavior.
[+]-lua name
Lua script file name
Specify manual feed for printer, if supported by the output device.
Use mode as the Metafont device name for path searching and font generation. This overrides any value from configuration files. With the default paths, explicitly specifying the mode also makes the program assume the fonts are in a subdirectory named mode.
Turns off automatic font generation ('mktexpk'). If 'mktexpk', the invocation is appended to a file missfont.log by default in the current directory. You can then execute the log file to create the missing files after fixing the problem. If the current directory is not writable and the environment variable or configuration file value 'TEXMFOUTPUT' is set, its value is used. Otherwise, nothing is written. The name missfont.log is overridden by the 'MISSFONT_LOG' environment variable or configuration file value.
At most num pages will be printed. Default is 100000.
Turns off structured comments such as '%%Page'; this might be necessary on some systems that try to interpret PostScript comments in weird ways, or on some PostScript printers. Old versions of TranScript in particular cannot handle modern Encapsulated PostScript. Beware: This also disables page movement, etc., in PostScript viewers such as Ghostview.
This will disable the use of Omega extensions when interpreting DVI files. By default, the additional opcodes 129 and 134 are recognized by dvips as Omega or pTeX extensions and interpreted as requests to set 2-byte characters.
This will disable the use of pTeX extensions when interpreting DVI files. By default, the additional opcodes 130 and 135 are recognized by dvips as pTeX extensions and interpreted as requests to set 3-byte characters, and 255 as request to change the typesetting direction.

The only drawback is that the virtual font array will (at least temporarily) require 65536 or more positions instead of the default 256 positions, i.e., the memory requirements of dvips will be somewhat larger. If you find this unacceptable or encounter another problem with the Omega or pTeX extensions, you can switch off the pTeX extension by using -noptex, or both by using -noomega (but please do send a bug report if you find such problems - see the bug address in the AUTHORS section below).

[+]-noluatex
Disable LuaTeX extensions
[+]-noToUnicode
Disable ToUnicode CMap file generation for OpenType fonts
Send output to the file name. If -o is specified without name (i.e., it is the last thing on the command line), the default is FILE.ps where the input DVI file was FILE.dvi. If -o isn't given at all, the configuration file default is used.

If name is '-', output goes to standard output. If the first character of name is '!' or '|', then the remainder will be used as an argument to popen; thus, specifying |lpr as the output file will automatically queue the file for printing as usual. (The MS-DOS version will print to the local printer device 'PRN' when name is |lpr and a program by that name cannot be found.)

-o disables the automatic reading of the PRINTER environment variable, and turns off the automatic sending of control-D. See the -f
option for how to override this.

Move the origin by X-OFFSET,Y-OFFSET, a comma-separated pair of dimensions such as .1in,-.3cm (*note papersize special::). The origin of the page is shifted from the default position (of one inch down, one inch to the right from the upper left corner of the paper) by this amount. This is usually best specified in the printer-specific configuration file.

This is useful for a printer that consistently offsets output pages by a certain amount. You can use the file 'testpage.tex' to determine the correct value for your printer. Be sure to do several runs with the same 'O' value--some printers vary widely from run to run.

If your printer offsets every other page consistently, instead of every page, your best recourse is to use bop-hook (*note PostScript hooks::).

Exactly analogous to -l (q.v.), but specifying the first page number to be printed (processed).
Print pages FIRST through LAST; equivalent to -pFIRST-lLAST, except that multiple -pp options accumulate, unlike -p and -l. The '-' separator can also be ':'.
Read the configuration file config.PRINTER ( PRINTER.cfg on MS-DOS), which typically sets the output name (most likely 'o |lpr -PPRINTER'), resolution, Metafont mode, and perhaps other printer-specific defaults. It works best to put sitewide defaults in the one master config.ps file and only things that vary from printer to printer in the config.PRINTER files; config.ps is read before config.PRINTER.

A configuration file for eventual creation of Adobe PDF files is provided in config.pdf and thus can be loaded with -Ppdf. It will try to include Type 1 outline fonts into the PostScript file (*note Hypertext caveats::).

If no -P or -o is given, the environment variable PRINTER is checked. If that variable exists, and a corresponding config.PRINTER ( PRINTER.cfg on MS-DOS) file exists, it is read. *Note Configuration file searching::.

Run in quiet mode. Don't chatter about pages converted, etc.; report nothing but errors to standard error.
[+]-Q
Skip VTeX private specials.
Output pages in reverse order. By default, page 1 is output first.
Run securely. -R2 disables both shell command execution in \special{} (via '`', *note Dynamic creation of graphics::) and config files (via the 'E' option, *note Configuration file commands::) and opening of any absolute or '..'-relative filenames. -R1, the default, forbids shell escapes but allows absolute filenames. -R0 allows both.
Causes the entire global output to be enclosed in a save/restore pair. This causes the file to not be truly conformant, and is thus not recommended, but is useful if you are driving the printer directly and don't care too much about the portability of the output.
Set the maximum number of pages in each `section'. This option is most commonly used with the -i option; see that documentation above for more information.
This sets the paper type to papertype. The papertype should be defined in one of the configuration files, along with the appropriate code to select it. (Currently known types include letter, legal, ledger, a4, a3). You can also specify a papertype of landscape, which rotates a document by 90 degrees. To rotate a document whose paper type is not the default, you can use the -t option twice, once for the paper type, and once for landscape. In general, you should not use any -t option when using a papersize special, which some LaTeX packages (e.g., 'hyperref') insert. One exception is when using a nonstandard paper size that is not already defined in config.ps; in this case, you need to specify -tunknown. Another exception is when producing multi-page files for further processing; use -t nopaper to omit any paper size information in the output. (If you just have a single page document, you can use -E to get pure EPSF output.)
Set the paper size to papersize, a comma-separated pair of dimensions such as '.1in,-.3cm' (*note papersize special::). It overrides any paper size special in the DVI file. Be careful, as the paper size will stick to a predefined size if there is one close enough. To disable this behavior, use -tunknown.
Use s as the title in the generated PostScript ('%%Title'). If not specified, the default is the basename of the input file; for example, running 'dvips /foo/bar.dvi' will have a '%%Title' of 'bar.dvi'.
Set psmapfile to be the file that dvips uses for looking up PostScript font aliases. If psmapfile begins with a + character, then the rest of the name is used as the name of the map file, and the map file is appended to the list of map files (instead of replacing the list). In either case, if psmapfile has no extension, then .map is added at the end.
Disable a PostScript virtual memory saving optimization that stores the character metric information in the same string that is used to store the bitmap information. This is only necessary when driving the Xerox 4045 PostScript interpreter. It is caused by a bug in that interpreter that results in `garbage' on the bottom of each character. Not recommended unless you must drive this printer.
Print the dvips version number and exit.
Download non-resident PostScript fonts as bitmaps. This requires use of 'mtpk' or 'gsftopk' or 'pstopk' or some combination thereof to generate the required bitmap fonts; these programs are supplied with Dvips. The bitmap must be put into 'psfonts.map' as the downloadable file for that font. This is useful only for those fonts for which you do not have real outlines, being downloaded to printers that have no resident fonts, i.e., very rarely.
[+]-W
Extended search for emTeX graphics.
Set the magnification ratio to num/1000. Overrides the magnification specified in the DVI file. Must be between 10 and 100000. It is recommended that you use standard magstep values (1095, 1200, 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total number of PK files generated. num may be a real number, not an integer, for increased precision.
Set the horizontal resolution in dots per inch to num.
Set the magnification ratio to num/1000 times the magnification specified in the .dvi file. See -x above.
Set the vertical resolution in dots per inch to num.
Pass html hyperdvi specials through to the output for eventual distillation into PDF. This is not enabled by default to avoid including the header files unnecessarily, and use of temporary files in creating the output.
Compress bitmap fonts in the output file, thereby reducing the size of what gets downloaded. Especially useful at high resolutions or when very large fonts are used. May slow down printing, especially on early 68000-based PostScript printers. Generally recommend today, and can be enabled in the configuration file (*note Configuration file commands::).

afm2tfm(1), tex(1), mf(1), dvips(1), dvitype(1), lpr(1), dvips.texi, README.overview.md, https://tug.org/dvips, https://github.com/vtex-soft/xdvipsk.

Xvipsk uses the same environment variables and algorithms for finding font files as TeX and its friends do. See the documentation for the Kpathsea library for details. (Repeating it here is too cumbersome.)

KPATHSEA_DEBUG: Trace Kpathsea lookups; set to -1 for complete tracing.

PRINTER: see above.

PostScript is a registered trademark of Adobe Systems Incorporated.

Dvips created by Tomas Rokicki; extended to virtual fonts by Don Knuth. Path searching and configuration modifications by Karl Berry.

Main extensions by Arūnas Povilaitis; fonts management by Mindaugas Piešina; lua callbacks, configuration, and maintenance by Sigitas Tolušis.

Maintained in TeX Live; please send bug reports or other correspondence related to dvips to tex-k@tug.org (https://lists.tug.org/tex-k) and related xdvipsk to tex-dev@vtex.lt (https://github.com/vtex-soft/xdvipsk)

06 February 2026