# I've just been asked to write a minimal working example (MWE), what is that?

I was posting some question about this strange thing LaTeX is doing when I try to compile my thesis. Someone asked me to provide a minimal example that reproduces the problem. My thesis is now a few hundred pages long and spans along ten different source files! How am I supposed to know what or where is the cause of the problem?

Do you have any hints or ideas on how should I go about producing such a small example?

• When posting a minimal working example, also consider posting what you have tried; community members might find this helping in trying to solve your problem. – Werner Jan 30 '13 at 1:51
• Why this question and a synthesis of the answer are not present in the help center? – Clément Jun 26 '14 at 17:33
• See Why does TeX require such elaborate MWE:s for a discussion why MWEs are useful (and sometimes even necessary). – moewe Aug 21 '15 at 14:58
• – Werner Aug 21 '15 at 18:45
• – Werner Oct 6 '15 at 19:05
• My thesis is now a few hundred pages long [...] If you're serious about writing a thesis in TeX, you'll be doing it in a versioned repository (say svn or mercurial or git), and you can trivially revert to a version from yesterday that has worked. You can then also trivially obtain the differences between the two, and use these to narrow down what broke and when. Not doing that results in questions like yours :( Use version control, people. It's not hard, and it's not only for software. – Reinstate Monica Nov 6 '15 at 16:57

This answer focuses more on minimalizing the code, rather than finding the source of the problem, as the top-voted answer does. It is intended to be concise and hands-on, but digestible rather than exhaustive. Suggestions for improvement welcome!

Here are some strategies for reducing your code, which will help you get better and faster answers, since it will be clearer what your problem is and the other users will see that you put some effort into producing a concise Minimal Working Example. Thanks for that!

Most likely, not all of these things will apply to your question, so just pick what does apply. However, it is advised that you provide the community with something that will reproduce the problem in the easiest way possible. Typically this requires code that starts with \documentclass and ends with \end{document} (if using LaTeX). It will allow readers to copy-and-paste-and-compile your code and see exactly what problems you might be experiencing.

What follows below are snippets of code; bad references imply that it should typically not be used, as it may not be part of the problem, while good references make suggestions that should be used instead. Note that these snippets should still form part of a larger, \documentclass...\end{document} structure as mentioned above.

# Document Class

\documentclass{MyUniversitysThesisClass}


\documentclass[..]{standalone}


...unless your problem relates to the standalone document class. standalone is meant for cropping stand-alone images within a main document usually. If this doesn't pertain to you, don't use it.

### ＋ Good:

\documentclass{article}


Using a non-standard document class? Does your problem still show up with article? Then use article.

# Document Class Options

\documentclass[12pt, a5paper, final, oneside, onecolumn]{article}


### ＋ Good:

\documentclass{article}


Using any options for your document class? Does your problem still show up without them? Then get rid of them.

\usepackage{booktabs} % hübschere Tabllen, besseres Spacing
\usepackage{colortbl} % farbige Tabellenzellen
\usepackage{multirow} % mehrzeilige Zellen in Tabellen
\usepackage{subfloat} % Sub-Gleitumgebungen


### ＋ Good:

\usepackage{booktabs}
\usepackage{colortbl}
\usepackage{multirow}
\usepackage{subfloat}


You put comments in your code to remember what packages are there for? Great habit, but usually not necessary in a MWE – get rid of them.

\usepackage{a4wide}
\usepackage{amsmath, amsthm, amssymb}
\usepackage{url}
\usepackage[algoruled,vlined]{algorithm2e}
\usepackage{graphicx}
\usepackage[ngerman, american]{babel}
\usepackage{booktabs}
\usepackage{units}
\usepackage{makeidx}
\makeindex
\usepackage[usenames,dvipsnames]{color}
\usepackage{colortbl}
\usepackage{epstopdf}
\usepackage{rotating}


### ＋ Good:

% Assuming your problem is related e.g. to the rotation of a figure, you might need:
\usepackage{rotating}


You’ve developed an awesome template with lots of helpful packages? Does your problem still show up if you remove some or even most of them? Then get rid of those that aren’t necessary for reproducing the problem. (If you should later find out that another package is complicating the situation, you can always ask another question or edit the existing question.)

In most cases, even packages like inputenc or fontenc are not necessary in MWEs, even though they are essential for many non-English documents in “real” documents.

# Images

\includegraphics{graphs/dataset17b.pdf}


### ＋ Good:

\usepackage[demo]{graphicx}
....
\includegraphics{graphs/dataset17b.pdf}


### ＋ Good:

\usepackage{graphicx}
....
\includegraphics{example-image}% Image from the mwe package


Your problem includes an image? Does your problem show up with any image? Then use the option demo for the package graphicx – this way, other users who don’t have your image file won’t get an error message because of that. If you prefer an actual image that you can rotate, stretch, etc., use the mwe package, which provides a number of dummy images, named e.g. example-image.

If your problem is specific to the size of the included image, still use mwe's example-image, but also specify the width and height so it more readily replicates your custom-image dimensions. Again, this way the problem is reproducible without using your image.

# Text

In \cite{cite:0}, it is shown that $\Delta \subset {U_{\mathcal{{D}}}}$. Hence
Y. Q. Qian's characterization of conditionally uncountable elements was a
milestone in constructive algebra. Now it has long been known that there exists
an almost everywhere Clifford right-canonically pseudo-integrable, Clairaut
subset \cite{cite:0}. The groundbreaking work of J. Davis on isomorphisms was a
major advance. In future work, we plan to address questions of uniqueness as
well as degeneracy. Thus in \cite{cite:0}, the main result was the
classification of meromorphic, completely left-invariant systems.


### ＋ Good:

\usepackage{lipsum} % just for dummy text
...
\lipsum[1-3]


### ＋ Good:

Foo bar baz.


Need a few paragraphs of text to demonstrate your problem? Use a package that produces dummy text. Popular choices are lipsum (plain paragraphs) and blindtext (can produce entire documents with section titles, lists, and formulae).

Need just a tiny amount of text? Then keep it maximally simple; avoid formulae, italics, tables – anything that’s not essential to the problem. Popular choices for dummy words are foo, bar, and baz.

# Bibliography Files

### ＋ Good:

\usepackage{filecontents}

\begin{filecontents*}{\jobname.bib}
@book{Knu86,
author = {Knuth, Donald E.},
year = {1986},
title = {The \TeX book},
}
\end{filecontents*}

\bibliography{\jobname} % if you’re using BibTeX
\addbibresource{\jobname.bib} % if you’re using biblatex


Need a .bib file to reproduce your problem? Use a maximally simple entry embedded in a filecontents environment in the preamble. During the compilation, this will create a .bib file in the same directory as the .tex file, so users compiling your code only need to save one file by themselves.

Another option for biblatex would be to use the file biblatex-examples.bib, which should be installed with biblatex by default. You can find it in bibtex/bib/biblatex/.

# Data

Never include data as an image.

Number of points    Values
10                   100
20                   400
30                  1200
40                  2345
etc...


### ＋ Good:

\usepackage{filecontents}

\begin{filecontents*}{data.txt}
Number of points, Values
10, 100
20, 400
30, 1200
40, 2345
\end{filecontents*}


Including the data as part of the MWE makes the example portable as well. Of course, the input may differ depending on what package you use to manage the data (some require CSV, some don't).

# Index

### ＋ Good:

\usepackage{filecontents}

\begin{filecontents*}{\jobname.ist}
delim_0 "\\dotfill "
\end{filecontents*}


The index style can be included in the filecontents* environment in the preamble. The contents (and file extension) will differ according to the required indexing application (makeindex or xindy).

Sometimes a problem can only be demonstrated with an index that spans several pages. The testidx package is like lipsum etc but the dummy text is interspersed with \index to make it easier to test index styles. It has over 400 top-level terms (along with some sub-items and sub-sub-items) that includes every basic Latin letter group (A–Z) as well some extended Latin characters and a few digraphs.

\begin{document}
aa\index{aa}
ab\index{ab}
...
zy\index{zy}
zz\index{zz}
\printindex
\end{document}


### ＋ Good:

\begin{document}
\testidx
\printindex
\end{document}


If page breaking is the source of your problem (for example, after a letter group heading or between an item and sub-item), there's a high probability of an awkward break occurring given the large number of test items, but you can alter the page dimensions or font size to ensure one occurs in your MWE.

# Glossaries

The glossaries package comes with some files containing dummy entries, which can be used in MWEs.

\newglossaryentry{sample1}{name={sample1},description={description 1}}
...
\newglossaryentry{sample100}{name={sample100},description={description 100}}
\newacronym{ac1}{ac1}{acronym 1}
...
\newacronym{ac100}{ac100}{acronym 100}


### ＋ Good:

\loadglsentries{example-glossaries-brief}


See Dummy Entries for Testing for a complete list of dummy entry files provided by glossaries. There's an additional file example-glossaries-xr.tex provided by glossaries-extra.

Formatting of code is done using Markdown. See the relevant FAQ How do I mark code blocks?. There also exists some syntax-highlighting, a discussion of which can be following at What is syntax highlighting and how does it work?.

With the above in mind, don't post your code in comments, since comments only support a limited amount of Markdown.

# Posting a Picture of Your Output

It’s often helpful to see what your current, faulty output looks like. If you’re not sure how to do that, have a look at How does one add a LaTeX output to a question/answer? and how can i upload an image to be included in a question or answer?.

Selection of packages inspired by Inconsistent rotations with \sidewaysfigure. Math ramble generated by Mathgen. Bibliography sample from lockstep’s question biblatex: Putting thin spaces between initials.

• This is excellent. We could use this as a basis for a more useful mwe tag wiki. – Charles Stewart Jan 31 '13 at 20:11
• Indeed, this is really great work! Thanks! – Jake Jan 31 '13 at 20:16
• @CharlesStewart Thanks! If others find this useful, we could either use it as a tag wiki, or link here from the tag wiki. I think I’d lean towards the latter option, just because collectively edited answers tend to see more action and “peer review” than tag wikis: Post edits displayed at the top of the main (meta) page, whereas a tag wiki edit is only (?) visible in the suggested edits history (if review is required), which I don’t think many people look at on meta. – doncherry Feb 2 '13 at 16:22
• I have to agree with Charles Stewart and Jake. This is a long-needed advice on how to create a MWE from already existing documents rather than to actually produce an example at all (i.e. Do-It-For-Me questions or “There is an error. Help!”). Re Comments: Not all comments in MWEs are bad. (Though, I agree that those package-describing comments are mostly unnecessary, and, interestingly, always in German.) Re mwe: It is actual not necessary to load (but to install) mwe, the images are included without it. Though, loading mwe has its perks as the manual’s chapter 2 elaborates. – Qrrbrbirlbel Feb 3 '13 at 1:43
• @Qrrbrbirlbel Re Comments: True, but I don’t expect users to follow these guidelines stubbornly. If they think they really need a comment, they’re gonna have it. Note how I even inserted comments myself for mwe and lipsum. Generally, I aimed at brevity and 90% accuracy, rather than 100% accuracy. Re mwe: The same idea applies here. I didn’t want to go through the pain of explaining how you can use a package’s files even if it’s not loaded. Loading it just makes everything easier – and I might even consider it good practice, just to indicate where the files come from. – doncherry Feb 3 '13 at 15:12
• @Speravir I purposely omitted kantlipsum because it doesn’t seem to add any functionality over lipsum, and it was more important to me to keep things simple rather than giving a complete overview of the options available. – doncherry Jan 26 '14 at 11:13
• There's a sample file called xampl.bib (installed with all TeX distributions) that can be used for dummy citations. (The glossaries package also comes with a load of dummy entries that can be used in MWEs.) – Nicola Talbot Aug 15 '14 at 10:48
• @Mico I’d argue that even though rotating loads graphicx anyway, it’s still good practice to load graphicx explicitly to get well-readable and comprehensible code, and also in case you want to add an option to graphicx later? – doncherry Mar 1 '15 at 15:35
• @doncherry - I fully agree with your proposition in general. It's just that the comment made the specific example explicitly about rotating a float; for such a use case, it should be ok to pare back the example a bit more and load only the rotating package, right? – Mico Mar 1 '15 at 19:24
• For some problem, dummy texs from lipsum and other package are not a good idea, as it could interfere with box decomposition mechanism (for example, in reledmac) – Maïeul Nov 24 '17 at 10:47
• There’s one piece of advice in there that I see differently: I often want to rasterize a MWE at a given dpi and have it fit within the size limits of TeX.SX. \documentclass[varwidth=...]{standalone} is great for that, although sometimes I need to insert a minipage environment instead. – Davislor Jan 31 '19 at 7:30

Most questions about code are made more answerable by the addition of a minimal working example (MWE) or short, self-contained, correct example (SSCCE).

Your question may have an obvious answer, or it may not. You the questioner probably do not know the difference between the two! So think about it from the point of view of the answerer. To ensure that the answer she provides is sound, she will probably want to create a sample document, make the changes she recommends, and check that it works. If she thinks she knows the answer but doesn't have the time to create a sample document, she may in the interest of quality control refrain from answering at this time.

So make it easy for potential answerers! Give them a block of code that can be copied, pasted directly into a file, compiled, tweaked, corrected, and pasted back.

Here minimal means that the problem is isolated and there is nothing in the sample that distracts from the error you have or the effect you desire. Working doesn't mean the problem is solved :-), it means the code sample can be copied-and-pasted and directly compiled.

The site sscce.org is dedicated to the topic. There are also several articles on the topic as it applies specifically to LaTeX:

## Errors

I didn't see your question, but I'm guessing that you got some error you haven't seen before, and said something to the effect of

I tried to compile, but I got the error Undefined control sequence.' How can I fix it?

This is next to impossible to answer, unless you expect only answers from psychics.

Instead, look at the line numbers, and post that paragraph or sentence, depending on the scope of the error. You'll have to add any referenced packages or other components which are critical to the compilation of the section, but make it as focused as possible on the part which is the source of the error.

If there are no helpful line numbers, (make a backup and then) begin removing things you added after the last successful compile. If you remove everything you just added, perform a binary search by removing halves of the document until you can narrow it down. Then, post the section which caused the problem.

A better approach to the "I tried to compile..." example above would be something like:

I am trying to typeset the following equation:

\documentclass{article}
\begin{document}
Alpha particles (named after and denoted by the first letter in the
Greek alphabet,$\alpha$) consist of two protons and two neutrons bound
together.
This means that an $\alfa$ particle is a helium nucleus.
\end{document}


But when I compile it with LaTeX I get this error message:

[22]
Undefined control sequence:
\alfa
An $\alfa$ particle is a helium nucleus.


What am I doing wrong?

## Enhancements

Other questions are not related to errors, but to a desired effect that the user wants to achieve, of the form:

I want to put (thing) at (place). How do I do that?

The MWE in this case should:

• be a full document including \documentclass, a preamble, \begin{document}, and \end{document}.
• include enough dummy text to make the document look like the one you're writing. The lipsum, kantlipsum and blindtext packages are helpful here in that they provide macros to make lots of text without actually having to type lots of text.
• have your best-so-far implementation of the desired effect.

Try to keep your vocabulary accessible—do not assume that because many experts in your field use TeX that all TeX users are familiar with your field. A question about typesetting affine Dynkin diagrams will not get answered until you find someone who knows TeX and math.

If you have enough reputation to include images, please do. Images of both the desired effect (mocked up or copied from another document), and the result of your best-so-far implementation. If you do not have enough reputation to include images, upload to http://imgur.com/ anyway and post the links (an editor will include the images for you). If you do not have enough reputation to post links, enter the bare URLs.

• I've never seen th abbreviation 'SSCCE': I think 'MWE' is much more common. – Joseph Wright Jul 29 '10 at 20:41
• SSCCE, I take it, is more often used on programming forums for Java and C. MWE is much more common in the TeX community after some recent research. Edited. – Kevin Vermeer Jul 29 '10 at 21:01
• Good answer, but this isn’t really an MWE, right? I thought that the point of MWEs is that they are complete working (La)TeX documents. – Konrad Rudolph Jul 30 '10 at 14:15
• @ Konrad - Good point. Edited! However, next time, feel free to edit it yourself. – Kevin Vermeer Jul 31 '10 at 15:34
• @Caramdir -- you seem to be the source of the suggestion "(make a backup)". i'd like to suggest an alternative (i hesitate to edit the text directly, as it's quite venerable by now): "make a copy (and edit that)". even if the source is under version control, it's usually not a good idea to make changes that might not get reverted when one is rushed into production. (to be continued with a different suggestion.) – barbara beeton Sep 22 '14 at 15:48
• another bit that might be added (although the text is already very long) is how to make a "minimal" image to insert. recently i've noticed a number of images that consisted of an entire, nearly empty, page, with text too small to be read. a link to a suitable explanation should suffice. i'm not sure there's an existing great answer, but that can be remedied; i'll try to research the available postings. – barbara beeton Sep 22 '14 at 15:50

Hopefully if your thesis is a few hundred pages long, you haven't been experiencing the problem you're asking about since you began it! If you were having the problem the whole time, then you could probably construct a minimal example basically by pretending to start a new thesis in the same way you started your existing one.

In the more likely scenario that you've just encountered a new problem, the best approach I've found is to start commenting out the newest pieces you've added one at a time and seeing when the problem goes away. At that point, you can try to make a new minimal document containing only the part you had to remove to make the problem go away -- if all goes well, you'll be able to make the new (much smaller) document reproduce the same problem.

It's actually not uncommon to end up finding the solution yourself when you start trying to construct a minimal example, but if that's not the case then once you have it you can add it to your original question to find help here.

Good luck!

• Binary search is usually the fastest solution. Remove roughly 1/2 of your thesis. If the problem persists, repeat. If not, undo and remove the other 1/2 of your thesis. Of course it isn't quite that straightforward always, but even if you have hundreds of pages of text, you can fairly quickly reduce the problem to a short fragment of code. – Jukka Suomela Jul 29 '10 at 20:34
• +1 for observing that this is a good way to debug the problem oneself – Norman Gray Jul 29 '10 at 21:23
• +1 for a newbie this is the most useful strategy. I am writing my thesis and I do this often. I also use binary search. – denilw Feb 8 '11 at 21:18
• For those like me who do not have a text editor that allows to comment part of your .tex, for the binary search you can use the verbatim package, which allow you to use \begin{comment} ... \end{comment} commands. – Gopi Jul 11 '11 at 13:55

Please note that the "minimal" in minimal working example means that the document should not contain any (yes any!) code which isn't related to the error. If a code line can be removed without changing the error/issue it doesn't belong into the example. If a non-standard class is used1 for the original document and the error/issue still happens with a standard class then a standard class should be substituted. This means normally article or, if \chapter is required, report or book).

It is not required to use the minimal class for a minimal working example! In fact it should be avoided to prevent issues with missing definitions which are present in any real class, cf. also "Why should the minimal class be avoided?".

1 Standard classes are: article, book, report and letter.

There’s a new package on CTAN called mwe, providing some features for creating MWEs. This is the announcement text:

mwe provides several files useful to create a minimal working examples (MWEs). A mwe` package is provided which loads a small set of often used packages for MWEs. In addition several different images are provided which will be installed in the TEXMF tree, so that they can be used in any (La)TeX document. This allows different users to easily share MWEs which include images commands without requiring to share image files or use replacement code.

See Martin’s announcement here on TeX.SX

• Thanks for posting it here. I was planning to do so, but I didn't found time yet. – Martin Scharrer May 10 '12 at 8:16

What is a minimal working example? is a work of some regulars of de.comp.text.tex. Here they describe in detail, how to produce a minimal working example.

• @reemrevnivek: Really? I'm not used to seeing that behaviour in StackOverflow. – Will Robertson Jul 30 '10 at 5:02
• @Will - There are some polls, and some examples with lots of answers, but the FAQs (or at least the ones I've read) are all one answer, sometimes with noise at the bottom. Click through the questions at the official FAQ – Kevin Vermeer Jul 30 '10 at 12:22

I think I could add prof. van Duck's tutorials.

Section 3 Asking effective questions on TeX.SE of his first article in TUGBoat 38:3, 2017 explains how to build an MWE.

Section 3 How to format a post in TeX.SE of his third article in TUGBoat 39:3, 2018 explains how to format your question.

• I really like the way you write in English in the TUGBoat because I understand almost everything without the need for a translation machine. And besides, you make me laugh: -) – AndréC Dec 28 '18 at 15:48
• @AndréC Thank you! I'm not a native speaker, hence my English is simple. – CarLaTeX Dec 28 '18 at 16:07

Well, you can't just post your whole thesis and expect people to debug it for you...

It shouldn't be that hard to know which part of your thesis is causing the problem. Error messages should help you pinpoint which section of your LaTeX code is the problem - they usually include a file name and line number. You can then copy and paste it on here without any doubt that it will get solved.

• :D Have you ever tried to debug problems in (La)TeX files? Btw, I'm seeding this question, pretending to be a real user having a problem with my thesis. – Juan A. Navarro Jul 29 '10 at 20:26