---
name: "perltex"
section: "1"
platform: "linux"
package: "texlive-doc"
version: "2026.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/perltex"
---

# perltex(1)

enable LaTeX macros to be defined in terms of Perl code

## NAME

perltex - enable LaTeX macros to be defined in terms of Perl code

## SYNOPSIS

perltex \[**--help**\] \[**--latex**=*program*\] \[**--**\[**no**\]**safe**\] \[**--permit**=*feature*\] \[**--makesty**\] \[*latex options*\]

## DESCRIPTION

LaTeX -- through the underlying TeX typesetting system -- produces beautifully typeset documents but has a macro language that is difficult to program.  In particular, support for complex string manipulation is largely lacking.  Perl is a popular general-purpose programming language whose forte is string manipulation.  However, it has no typesetting capabilities whatsoever.

Clearly, Perl's programmability could complement LaTeX's typesetting strengths.  **perltex** is the tool that enables a symbiosis between the two systems.  All a user needs to do is compile a LaTeX document using **perltex** instead of **latex**.  (**perltex** is actually a wrapper for **latex**, so no **latex** functionality is lost.)  If the document includes a `"\usepackage{perltex}"` in its preamble, then `"\perlnewcommand"` and `"\perlrenewcommand"` macros will be made available.  These behave just like LaTeX's `"\newcommand"` and `"\renewcommand"` except that the macro body contains Perl code instead of LaTeX code.

## OPTIONS

**perltex** accepts the following command-line options:

- **--help**

  Display basic usage information.

- **--latex**=*program*

  Specify a program to use instead of **latex**.  For example, `"--latex=pdflatex"` would typeset the given document using **pdflatex** instead of ordinary **latex**.

- **--**\[**no**\]**safe**

  Enable or disable sandboxing.  With the default of **--safe**, **perltex** executes the code from a `"\perlnewcommand"` or `"\perlrenewcommand"` macro within a protected environment that prohibits \`\`unsafe'' operations such as accessing files or executing external programs.  Specifying **--nosafe** gives the LaTeX document *carte blanche* to execute any arbitrary Perl code, including that which can harm the user's files.  See Safe for more information.

- **--permit**=*feature*

  Permit particular Perl operations to be performed.  The **--permit** option, which can be specified more than once on the command line, enables finer-grained control over the **perltex** sandbox.  See Opcode for more information.

- **--makesty**

  Generate a LaTeX style file called *noperltex.sty*.  Replacing the document's `"\usepackage{perltex}"` line with `"\usepackage{noperltex}"` produces the same output but does not require PerlTeX, making the document suitable for distribution to people who do not have PerlTeX installed.  The disadvantage is that *noperltex.sty* is specific to the document that produced it.  Any changes to the document's PerlTeX macro definitions or macro invocations necessitates rerunning **perltex** with the **--makesty** option.

These options are then followed by whatever options are normally passed to **latex** (or whatever program was specified with `"--latex"`), including, for instance, the name of the *.tex* file to compile.

## EXAMPLES

In its simplest form, **perltex** is run just like **latex**:

```
    perltex myfile.tex
```

To use **pdflatex** instead of regular **latex**, use the **--latex** option:

```
    perltex --latex=pdflatex myfile.tex
```

If LaTeX gives a \`\``"trapped by operation mask"`'' error and you trust the *.tex* file you're trying to compile not to execute malicious Perl code (e.g., because you wrote it yourself), you can disable **perltex**'s safety mechansisms with **--nosafe**:

```
    perltex --nosafe myfile.tex
```

The following command gives documents only **perltex**'s default permissions (`":browse"`) plus the ability to open files and invoke the `"time"` command:

```
    perltex --permit=:browse --permit=:filesys_open
      --permit=time myfile.tex
```

## ENVIRONMENT

**perltex** honors the following environment variables:

- PERLTEX

  Specify the filename of the LaTeX compiler.  The LaTeX compiler defaults to \`\``"latex"`''.  The `"PERLTEX"` environment variable overrides this default, and the **--latex** command-line option (see "OPTIONS") overrides that.

## FILES

While compiling *jobname.tex*, **perltex** makes use of the following files:

- *jobname.lgpl*

  log file written by Perl; helpful for debugging Perl macros

- *jobname.topl*

  information sent from LaTeX to Perl

- *jobname.frpl*

  information sent from Perl to LaTeX

- *jobname.tfpl*

  \`\`flag'' file whose existence indicates that *jobname.topl* contains valid data

- *jobname.ffpl*

  \`\`flag'' file whose existence indicates that *jobname.frpl* contains valid data

- *jobname.dfpl*

  \`\`flag'' file whose existence indicates that *jobname.ffpl* has been deleted

- *noperltex-#.tex*

  file generated by *noperltex.sty* for each PerlTeX macro invocation

## NOTES

**perltex**'s sandbox defaults to what Opcode calls \`\``":browse"`''.

## SEE ALSO

[**latex**(1)](/latex/1.md), [**pdflatex**(1)](/pdflatex/1.md), [**perl**(1)](/perl/1.md), [**Safe**(3pm)](/Safe/3pm.md), [**Opcode**(3pm)](/Opcode/3pm.md)

## AUTHOR

Scott Pakin, *scott+pt@pakin.org*