# Include source code in Latex with “Listings”

First include the “listings”-package into your document:
 \usepackage{listings}

Basics

Now you have basically two possibilities. Either you type/copy your source code directly into the Latex document:
 \begin{lstlisting} place your source code here \end{lstlisting} 
The other possibility is to directly include the source file:
 \lstinputlisting{filename.java} 
This is particularly useful if you are still editing your source code. Obviously, Latex will always include the latest version of the source while generating the PDF-file.

Supported languages

The listings package does not only support java source code, but there is an exhaustive list of languages which are known to the package:
ABAP (R/2 4.3, R/2 5.0, R/3 3.1, R/3 4.6C, R/3 6.10), ACSL Ada (83, 95), Algol (60, 68), Ant, Assembler (x86masm), Awk (gnu, POSIX), bash, Basic (Visual), C (ANSI, Handel, Objective, Sharp), C++ (ANSI, GNU, ISO, Visual), Caml (light, Objective), Clean, Cobol (1974, 1985, ibm), Comal 80, csh, Delphi, Eiﬀel, Elan, erlang, Euphoria, Fortran (77, 90, 95), GCL, Gnuplot, Haskell, HTML, IDL (empty, CORBA), inform, Java (empty, AspectJ), JVMIS, ksh, Lisp (empty, Auto), Logo, make (empty, gnu), Mathematica (1.0, 3.0), Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modula-2, MuPAD, NASTRAN, Oberon-2, OCL (decorative, OMG), Octave, Oz, Pascal (Borland6, Standard, XSC), Perl,PHP, PL/I,Plasm, POV,Prolog, Promela,Python, R,Reduce, Rexx,RSL, Ruby, S (empty, PLUS), SAS, Scilab, sh, SHELXL, Simula (67, CII, DEC, IBM), SQL, tcl (empty, tk), TeX (AlLaTeX, common, LaTeX, plain, primitive), VBScript, Verilog, VHDL (empty, AMS), VRML (97), XML, XSLT.

Custom code formatting

You can customise the way how your code is displayed by using:
 \lstset{...} 

The following is a list of parameters, which can be used inside the previous command

language=Octave -> choose the language of the code
basicstyle=\footnotesize -> the size of the fonts used for the code
numbers=left -> where to put the line-numbers
numberstyle=\footnotesize -> size of the fonts used for the line-numbers
stepnumber=2 -> the step between two line-numbers.
numbersep=5pt -> how far the line-numbers are from the code
backgroundcolor=\color{white} -> sets background color (needs package)
showspaces=false -> show spaces adding particular underscores
showstringspaces=false -> underline spaces within strings
showtabs=false -> show tabs within strings through particular underscores
frame=single -> adds a frame around the code
tabsize=2 -> sets default tab-size to 2 spaces
captionpos=b -> sets the caption-position to bottom
breaklines=true -> sets automatic line breaking
breakatwhitespace=false -> automatic breaks happen at whitespace
morecomment=[l]{//} -> displays comments in italics (language dependent)

If you are using several parameters, they have to be separated by commas.
Example:
 \lstset{numbers=left, stepnumber=2, frame=single,} 

You might want to have a caption as well as reference the listing later:
 \lstset{language=Java, caption=Descriptive Caption Text, label=DescriptiveLabel} 

For an exhaustive list of available options to customize your included source code, refer to the documentation on CTAN.

Tricks

The following will draw a frame around your source code with a blue shadow (you will need the color-package).
 \lstset{frame=shadowbox, rulesepcolor=\color{blue}} 

If you want closed frames on each page, use the following command sequence:
 \begin{framed} \begin{lstlisting}...\end{lstlisting} or \lstinputlisting{...} \end{framed} 

#### 51 responses to “Include source code in Latex with “Listings””

• Katie

Oh, this is brilliant. I have always used the verbatim-environment. but this has so much more options. great.

• Steven

I have read great things about the listings package but in reality it is causing me lots of problems. I am writing a paper and have to include listings in an enumerated list to answer question numbers
1/ I have indented my source file to make easier reading/construction – if I have the listing section indented it is reflected in the pdf output! (using pdflatex) which is just madness
2/ The resulting text just looks ugly with incredibly bad spacing – the character kerning is completely messed up. Currently using the following setup:

\documentclass[11pt,a4paper,oneside,onecolumn]{article}
\usepackage{amsmath,amssymb,harvard}
\usepackage{amsfonts}
\usepackage{amsthm}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{harvard}
\usepackage{listings}
\usepackage{algorithm2e}
\renewcommand{\labelenumii}{(\roman{enumii})}
\renewcommand{\labelenumiii}{(\alph{enumiii})}
\renewcommand{\labelenumiv}{(\roman{enumiv})}
\begin{document}
\lstset{basicstyle=\footnotesize,language=HTML}
\bibliographystyle{plain}

I will try to find a solution and see which package is conflicting (if any) but the result is really ugly and \verb is starting to look good…

• Cesar

That’s nice and simple.

I was wondering, why Java is not supported?

• tom

Hi Cesar

Java is actually supported by the listings package. It appears in the list of supported languages above.

Tom

• Cesar

Oops… I sure need glasses

• Frank

Very interesting, nice post! Please keep up the good work!

• Rikke

I’m having problems using lstinputlisting{}

I guess that I should use something like C:\Users\Rikke\Documents\…\filename.R

But it doesn’t work – have you any idea why?

:o) Rikke

• tom

Hi Rikke,

As a starting directory, Latex will always use the location of your main document (where you have \documentclass{...}).
To move upwards the directory-tree, you simply use “..\”.
E.g. imagine you have a directory, with two folders, “code” and “report”. Inside “report”, you have your Latex-files and in “code” you have the source files. To include the source files, you would type:

\lstinputlisting{..\code\filename.R}

Cheers,
Tom

• Quiron

Thanks for your work! it’s realy good!

• Lorenzo

May I suggest as an alternative GNU Source-highlight: http://www.gnu.org/software/src-highlite/

this is not a LaTeX package, but it produces latex output

• links for 2008-10-18 « Iveney’s Weblog

[...] Include source code in Latex with “Listings” « Blog on Latex Matters (tags: listings latex src) [...]

• Joe Python

If you have python distribution in your machine you can use ‘pygmentize’. Using pygmentize you can also generate syntax highlighted code in Word, html and pdf formats besides LateX.

• nguyenminhhaivn

@steven: You’ve said “The resulting text just looks ugly with incredibly bad spacing – the character kerning is completely messed up”. I finally found out that the “columns” option can solve your problem. The complete command is \lstset{columns=fullflexible}.

• Philip Machanick

The main problem I had with setting Awk scripts in verbatim mode is that single quotes are turned into curly apostrophes, making it awkward to copy and paste a typset example into a terminal or editor window to execute. Double quotes are OK in verbatim mode. Using lstlisting mode, ALL quotes are turned into curly quotes, one worse than verbatim.

Any ideas? The simplest thing to make a listing in any mode without curling quotes would be good. Thanks.

• Philip Machanick

\usepackage{upquote}

after all other font specs will force typewriter font to Computer Modern Typewriter and make verbatim, verbatim*, verb, and verb* leave  and ‘ in their original state.

(” is already set unchanged; I’m not sure of the logic of curling ‘ and  in a mode that otherwise leaves things unchanged. While it’s true that the old ASCII character set didn’t include encodings for these so it’s useful to be able to create them in verbatim mode, not having an obvious escape to get back to raw apostrophes and grave accents seems to me an omission).

Not quote as fancy as the listings package but for simple scripts and one-liners, being able to get the various verbatim modes to behave is good. Unless you need the default behaviour for some other purpose in the same document …

• Emerson

Thansk Phillip for \usepackage{upquote}.

I was looking for this solution.

But I have another one. How to use a source code with accent (i.e. é, á, â, ã, etc.) in a utf8 enconding?

I have tried \usepackage[utf8]{inputenc} and \lsset{extendedchars=\true,inputencoding=utf8} but without success.

• tom

Hi there!

Actually, you don’t need any package to do this. Try this: \'{e}\'{a}\^{a}\~{a}.

Cheers,
Tom.

• James Pyles

Thanks, Phillip. the \usepackage{upquote} solution was just was just what I was looking for.

God mainly bless you for this page. It was a blessing for me to know how to put my SAS-Code into my latex document. So i just want to acknowledge and to thank you for it.

Can we put the code without frame and without numbering?

• tom

You can use the following options to omit the frame and numbering:

frame=none, numbers=none

You can find the documentation of the listings package here.

• Jon

Thanks for the post. It was useful for dumping code into latex and not worrying about escaping and formatting.

• Alexander Pokluda

Here’s a line that creates a floating listing using \lstinputlisting :

\lstinputlisting[float,caption=A floating example,label=R10]{R10.m}
• Geoffrey Knauth

Thanks. I’m going to try this. I’ve also used and liked the lgrind package.

• Phil

I wanted this package to look a bit like the verbatim text. This can be achieved, by:

\lstset{basicstyle=\small\ttfamily, basewidth=0.51em}.

Thought it might be worth mentioning as it took me a while to find this.

• i82much

I cannot get the lstlisting to work with autoref – if I attempt to wrap the listing in a labeled figure and then reference it, I jump to a random place on a page near the figure, but not at the figure itself. This is very frustrating. Has anyone figured a workaround for this?

• wolverenstein

I’ve found a workaround for people, like me, who’s using UTF8 as encoding: ‘listingsutf8′. This package provides support for those ‘strange’ characters when using the \lstinputlisting command.

Be aware that ‘listings’ package (as far as I read) doesn’t support multi-byte encodings (UTF8 and others), but only one-byte encoding. The trick of ‘listingsutf8′ is to translate a text file (the source code) to an encoding that ‘listings’ can understand… And hope, as well, that you understood me

So, it’s not a final solution, but works.

• Erik

Thanks for mentioning this. It’s a great package to quickly list some source code.

• 71ga

Is there any way to change the name of Listing like i can do with chapters (\renewcommand\chaptername{new_chapter_name}) ???

• Gaya

I used the lstlisting for my code and used latex2pdf to create a pdf file.
When I copy and paste the source code from a pdf generated file, it losses its formatting. What can I do about this?

• anibalismo

Thanks dude! you were very helpful!!!

• Allusion

Hi there. I tried the listings package too. Everything would have been wonderful… if copying code chunks were not such a pain. Did somebody manage to do this properly?

columns=flexible or columns=fixed have both severe problems, the first ruins my indentation, the second adds weird phantom spaces throughout my code. Thanks.

• tom

Hello!
Probably easier than copying the code is to include it directly from the source file. I described how to do that in the post above.
The problem with the columns-option is known. If you don’t need it, just drop it. If you think you need it, please provide a minimal example. I will then try to help you…
I created a few code highlighting examples some time ago that you may find useful.
Tom.

• Jasper Koehorst

Oke I used pygmentize to get the code working but that doesn’t really matters… I was wondering how you refer to the code? At the moment I use \figure to do this but i was wondering if there is something called \code to use as a reference so in the text will be something like…

As can be seen in code 2.5 or something similar.

Any ideas?

• tom

I wouldn’t know of anything like that. But you can always define it yourself:

\newcommand{\code}[1]{source code \ref{#1}}
...
See \code{code:example1}.

Tom.

• Iray

Hi Jasper,

How do you use pygmentize? If I can recall correctly, it only outputs fancyvrb env’s and not lstlistings

• Iray

Hi Tom,

Do you know a way of starting the numbering at line 3 say without clipping lines number 1 and 2?

• tom

Hi Iray,

The listings package covers that. Use the firstnumber=x key-value-pair.

\begin{lstlisting}[firstnumber=3,numbers=left]
...
\end{lstlisting}

Best, Tom

• Iray

Hi, Tom,

Sorry, I’m afraid I wasn’t very clear. I want numbering to start at line 3, with that line numbered 1

#she-bang (line 1 not numbered but shown)
(line 2 not numbered but shown)
import math (line 3 would be numbered with 1)
(line 4 would be numbered with 2)

and so on.

I knew about firstnumber and have already tried firstnumber=-1 but the pbm is I can’t see anywhere in the listings manual how to turn off the numbering for these first two lines or at least how to do it on a line by line basis.

• tom

Hi Iray. Ok, I see. I found something that should do the trick on this blog. Hopefully it works for you. Best, Tom.

• David Jaeger

Has anyone modified this to use with Stata code?

• Robert

I am trying to write a Latex document that explains what various parts of my code are doing, section-by-section.
Sometimes it is better to show just a few lines at the start and end of each section and use dots in between.

Is there any way to do that which doesn’t require me just to manually delete the body of the section and add a \dots or similar?

For example, something like

\displaysourcecodesection[1-3,10-12]{ section of code here }

that would show only lines 1, 2 and 3 followed by dots and then lines 10, 11 and 12.

It would allow me to not have to delete parts of my source code from the .tex file and would allow me flexibility to get the final balance right of how much of each section I want to show in the final output.

Thanks

• Smith

Thanks man. Really great explanation of listings.

• Bhavani A B

• Jack

I am trying to include source code from a gnuplot script, but some of the lines are apparently being interpreted as LaTex commands. This is an example line with a problem. Is there a way to turn off interpretation of LaTex keywords within a listing?

set xlabel “Particle Velocity (cm/{/Symbol \155}S)” font “Helvetica,18″ offset char 0, char -1

• tom

Hi Jack,

Interesting question. I tried to reproduce your problem. The only thing I saw was an issue with the double quotes you are using. You would have to load the right encoding in order to make them display correctly. You could also replace them with standard double quotes (open and close the same) and then use standard encoding as in the code below.

\documentclass[11pt]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{xcolor, listings}

\definecolor{lightgrey}{rgb}{0.9,0.9,0.9}
\definecolor{darkgreen}{rgb}{0,0.6,0}

\lstset{language=Gnuplot,
breaklines=true,
keywordstyle=\color{darkgreen},
otherkeywords={\$, \{, \}, $,$},
backgroundcolor=\color{lightgrey}}
\begin{document}

\begin{lstlisting}
set xlabel "Particle Velocity (cm/{/Symbol \155}S)" font "Helvetica,18" offset char 0, char -1
\end{lstlisting}

\end{document}

If this didn’t solve your problem, please post a minimal example similar to the one I provided.

Thanks, Tom