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, Eiffel, 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}
April 4th, 2008 at 10:56 am
Oh, this is brilliant. I have always used the verbatim-environment. but this has so much more options. great.
April 5th, 2008 at 7:53 am
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} \headheight 14pt \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…
April 6th, 2008 at 4:56 pm
That’s nice and simple.
I was wondering, why Java is not supported?
April 6th, 2008 at 8:08 pm
Hi Cesar
Java is actually supported by the listings package. It appears in the list of supported languages above.
Tom
April 7th, 2008 at 11:52 pm
Oops… I sure need glasses
April 17th, 2008 at 6:25 pm
Very interesting, nice post! Please keep up the good work!
April 21st, 2008 at 12:24 pm
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?
) Rikke
April 21st, 2008 at 4:45 pm
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
May 1st, 2008 at 4:12 pm
Thanks for your work! it’s realy good!
October 3rd, 2008 at 10:04 am
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
October 18th, 2008 at 3:02 pm
[...] Include source code in Latex with “Listings” « Blog on Latex Matters (tags: listings latex src) [...]
October 28th, 2008 at 3:39 pm
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.
November 12th, 2008 at 12:10 pm
@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}.
November 28th, 2008 at 6:16 am
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.
November 30th, 2008 at 11:14 pm
Answered my own question:
\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 …
September 29th, 2009 at 7:30 pm
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.May 8th, 2010 at 8:55 pm
Hi there!
Actually, you don’t need any package to do this. Try this:
\'{e}\'{a}\^{a}\~{a}.Cheers,
Tom.
January 13th, 2009 at 10:42 pm
Thanks, Phillip. the
\usepackage{upquote}solution was just was just what I was looking for.February 26th, 2009 at 5:15 pm
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.
February 26th, 2009 at 6:58 pm
Can we put the code without frame and without numbering?
February 26th, 2009 at 7:00 pm
Hi Nadine,
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.
February 26th, 2009 at 10:09 pm
Thanks for the post. It was useful for dumping code into latex and not worrying about escaping and formatting.
September 29th, 2009 at 9:05 pm
Here’s a line that creates a floating listing using
\lstinputlisting:\lstinputlisting[float,caption=A floating example,label=R10]{R10.m}November 21st, 2009 at 2:07 pm
Thanks. I’m going to try this. I’ve also used and liked the lgrind package.
March 24th, 2010 at 12:16 pm
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.
May 5th, 2010 at 3:23 am
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?
May 7th, 2010 at 5:32 pm
Please post a minimal example, so I can have a look at it.
Thanks,
Tom.
July 14th, 2010 at 2:15 pm
As I recall, the “recommended” way of referring to a listing is to use
\begin{lstlisting}[label=myCoolListing] ... \end{lstlisting}New paragraph where I can refer to
\autoref{myCoolListing}This works great in my case, at least.
(If you RTFM (p. 16, and F stands for Fine in this case) at ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf, there are a lot of tips for customizing this)
March 1st, 2011 at 8:14 pm
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.
July 4th, 2011 at 9:29 am
Thanks for mentioning this. It’s a great package to quickly list some source code.
July 8th, 2011 at 2:08 pm
Is there any way to change the name of Listing like i can do with chapters (\renewcommand\chaptername{new_chapter_name}) ???
July 8th, 2011 at 2:27 pm
I have figured this one out. You can change names using this command: \renewcommand\lstlistingname{Program}
October 1st, 2011 at 5:13 pm
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?
October 3rd, 2011 at 8:02 am
Hi Gaya,
You may find some answers here to solve your problem.
Tom.
October 3rd, 2011 at 3:23 pm
Thanks dude! you were very helpful!!!
October 5th, 2011 at 3:06 pm
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.
October 7th, 2011 at 3:55 am
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.
October 10th, 2011 at 8:26 am
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?
October 10th, 2011 at 9:13 am
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.
October 13th, 2011 at 10:49 pm
Hi Jasper,
How do you use pygmentize? If I can recall correctly, it only outputs fancyvrb env’s and not lstlistings
October 13th, 2011 at 10:51 pm
Hi Tom,
Do you know a way of starting the numbering at line 3 say without clipping lines number 1 and 2?
October 14th, 2011 at 5:45 am
Hi Iray,
The
listingspackage covers that. Use thefirstnumber=xkey-value-pair.\begin{lstlisting}[firstnumber=3,numbers=left] ... \end{lstlisting}Best, Tom
October 14th, 2011 at 3:46 pm
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.
October 17th, 2011 at 1:22 pm
Hi Iray. Ok, I see. I found something that should do the trick on this blog. Hopefully it works for you. Best, Tom.
January 30th, 2012 at 1:23 am
Has anyone modified this to use with Stata code?
February 22nd, 2012 at 1:52 pm
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
February 23rd, 2012 at 1:25 pm
Hey Robert,
That’s an interesting question, thanks. I found this question (and answer) on stackexchange that may help you put together a command that solves your problem.
Let me know if it works out!
Best, Tom.
August 16th, 2012 at 7:34 pm
Thanks man. Really great explanation of listings.