Skip to main content
Use listings when you need portable code blocks with no external highlighter. Use minted when syntax quality matters and the build environment provides the latexminted executable and Pygments. On current TeX Live 2024+ installations, minted v3 can normally use trusted restricted shell escape without the unsafe global -shell-escape flag.
Quick answer: choose listings for journals, CI systems, or editors where external commands may be unavailable. Choose minted for richer Pygments highlighting. TeX Live 2024+ with minted v3 usually compiles normally; older TeX Live and some MiKTeX setups require explicit permission for latexminted.Related topics: Text formatting | Fonts | Headers & footers | Errors

​
listings vs minted

​
Choose in 30 seconds

  • Choose listings if the PDF must compile anywhere, the source is untrusted, or the publisher controls the build.
  • Choose minted if highlighting quality matters and you control or have verified the toolchain.
  • Choose listings when you are unsure. You can switch later without changing the surrounding document structure.

​
Quick Start

​
Minimal listings setup

Use this when you want a simple code block and do not want to change your compiler settings.

​
Minimal minted setup

Use this when you want Pygments syntax highlighting and the build environment provides minted v3 and latexminted. With an up-to-date TeX Live 2024+ installation, compile normally:
For older TeX Live releases, full shell escape may still be required:
Full -shell-escape allows LaTeX to run arbitrary system commands. Use it only for documents you trust. Prefer current minted v3 with the restricted latexminted executable, or use listings in untrusted and locked-down environments.

​
The usual minted failure

If minted does not compile, the problem is usually one of these:
  • minted, latexminted, or its Python dependencies are not installed
  • the TeX distribution does not permit latexminted through restricted shell escape
  • an older TeX Live or MiKTeX setup needs explicit permission
  • the editor, CI runner, or publisher blocks all external commands
If you cannot change the build setup, use listings instead.
LaTeX Cloud Studio keeps unrestricted -shell-escape disabled for untrusted compilation. Use listings for guaranteed portability. minted v3 may work through the restricted, trusted latexminted path when it is available in the active compiler image.

​
Cache highlighted code for restricted builds

minted caches highlighted output in _minted by default. If the final build cannot run latexminted, generate the cache in an allowed environment and then enable frozencache: Keep the generated cache with the document. With frozencache=true, compilation fails when a required cache entry is missing instead of trying to execute the highlighter. This is useful for publisher and CI workflows, but listings remains simpler when cached artifacts are not accepted.

​
Inline code

For short snippets inside a paragraph:

​
The listings Package

​
Basic Code Formatting

Expected output:

Expected output

A code block with a light gray background and single-line frame border. Line numbers (1-10) appear in the left margin in a subtle gray color. The Python code displays in a monospace font with consistent formatting: the function definition, docstring, conditional logic, and loop are all clearly visible with proper indentation preserved.

​
Language-Specific Styling

Expected output:

Expected output

Language-specific syntax highlighting - Each style applies different colors and formatting:
  • Python style: Blue keywords, red strings, gray comments, light blue background with left border
  • Java style: Purple keywords, orange strings, green comments, top/bottom frame
  • C++ style: Blue keywords, dark red strings, green comments, rounded frame
The code appears in a monospace font with proper indentation and language-specific keyword coloring.

​
Custom Language Definitions

​
The minted Package

​
Basic minted Setup

minted v3 uses the latexminted executable and Pygments. TeX Live 2024+ normally permits latexminted through restricted shell escape; older TeX Live and some MiKTeX configurations need explicit permission. Do not enable unrestricted shell escape for untrusted documents.

​
Advanced minted Styling

​
Highlighting Specific Lines

​
Code Listings in Floats

​
Floating Code Listings

​
Code Listings with Subfigures

​
Inline Code and Escaping

​
Inline Code with Special Characters

​
Performance and Customization

​
Custom Color Schemes

​
Code Import from Files

​
Best Practices

Code formatting guidelines:
  1. Choose appropriate package - Use listings for simple formatting, minted for syntax highlighting
  2. Consistent styling - Define styles once and reuse throughout document
  3. Font size - Use \footnotesize or \small for better readability
  4. Line numbers - Include for longer code blocks, omit for short snippets
  5. Break long lines - Enable breaklines for better page layout
  6. Escape special characters - Use proper delimiters for inline code

​
Production-Ready Setup

​
Troubleshooting & FAQ

First confirm that minted v3 and latexminted are installed and available on PATH. TeX Live 2024+ normally permits latexminted through restricted shell escape. Older TeX Live or MiKTeX may require an explicit trusted-command configuration or, for trusted documents only, full shell escape. If you cannot change the environment, use listings or a complete frozen cache.
minted v3 performs highlighting through latexminted, which uses Pygments. A current TeX package manager may install these components together; otherwise install latexminted and its dependencies in the Python environment used by the compiler. A document with a complete frozen cache no longer needs Python or Pygments during the final build.
Use listings for lightweight, dependency-free code blocks; choose minted for high-quality syntax highlighting and extensive styling. For journal-ready output, minted is usually preferred.
Use current minted v3 on TeX Live 2024+ through its trusted restricted executable, use a verified frozen cache, or choose listings. If a journal or CI service forbids external execution and cached artifacts, listings is the portable choice.
Ensure your document isn’t forcing monochrome (e.g., via print mode) and that options like bgcolor, highlightlines, and frame are set on the environment or via \setminted{...}.

​
Quick Reference

​
Essential Commands

​
Common Options

​
Supported Languages

Both packages support many languages including:
  • Python, Java, C++, C, JavaScript, TypeScript
  • HTML, CSS, SQL, LaTeX, Bash, PowerShell
  • Go, Rust, Swift, Kotlin, Scala, Haskell
  • MATLAB, R, Julia, Perl, Ruby, PHP
Next: Learn about Headers and footers for page decoration and numbering, or explore Multiple columns for layout.