Please help me in embedding plantUML diagram in the LyX document.

I am new to LyX, I could not figure out how to generate the diagram on the fly while converting the doc to the PDF.

Let me write down on high level what I want to achieve.

  1. Add a file format .plantuml
  2. Add a converter for this file format, which will convert .plantuml to PNG
  3. Include the .plantuml file in the master LyX document.
  4. When I run the export to PDF. I should see image included in the PDF file.

Please guide me how to achieve this.

  • Hi, welcome to TeX.sx. Where does this diagram come from, how have/will you create it? Jan 15, 2014 at 9:04
  • Note an email by the OP on the lyx-users list: mail-archive.com/lyx-users@lists.lyx.org/msg97772.html
    – scottkosty
    Jan 16, 2014 at 16:15
  • Torbjorn T - These are UML diagram. Plantuml is very good tool to create diagram using the simple text command. This tool is used a lot by developer community. So requirement was when i Include this text file into master lyx file I should see the diagram instead of text. This is what we are trying to achieve here Hope it helps ! Jan 19, 2014 at 18:52

2 Answers 2


I'm writing a separate answer, since a lot of factors finally matter when getting PlantUML to PDF:

Using SVG rather than PNG or EPS

SVG as an intermediate format has advantages over PNG and EPS. The PDF can contain the original text elements from the PlantUML diagram (e.g., class names, methods, comments, etc.), which could be useful for searching, indexing, copying, etc. in the PDF. Using PNG not only loses definition (it's raster as opposed to vectorial), it also loses the text information. Even though EPS is vectorial, my experience with EPS in LyX in PDF is that I lose the text, as it appears to be converted to outlines.

SVG is not without troubles in LyX, however. Inkscape must be properly installed and visible via LyX. LyX may or may not do this, depending on the platform. A good way to verify it is to run the Reconfigure command in LyX and to look at the Messages window. You should see that it finds inkscape in the list of environments it's looking for. If LyX doesn't find it, make sure you've added the inkscape executable to the Path in LyX Preferences. On my Windows 8.1 system, it wasn't installed by default.

Another trouble I found with SVG (at least in Windows) is with the mapping of fonts. On my Windows 8.1 PC, PlantUML by default generates SVG files using a font that shows up as "sans-serif" in inkscape. The font inkscape uses for "sans-serif" looks like Lucida or maybe MS Sans Serif, and it is actually wider than the one that PlantUML used to lay out the diagram before it generated the SVG. This results in text in the SVG (and the PDF later) that is too wide, e.g.:

enter image description here

One solution I found was to specify the Font in my PlantUML diagram as follows:

skinparam defaultFontName Arial Unicode MS

This way, PlantUML and inkscape use the same specific font, and there are no mistakes with the layout. One caveat with this strategy, however, is that fonts are system-dependent. That means Arial Unicode MS is one of the fonts installed on my Windows 8.1 machine and the above PlantUML statement probably won't work on a Linux system or MacOS. The advice from PlantUML's site is finally:

Please note the fontname is highly system dependent, so do not over use it, if you look for portability. Helvetica and Courier should be available on all system.

A cool feature of PlantUML is the listfonts statement. Put it as the first line after @startuml in a PlantUML file and you'll get a list of all the fonts PlantUML can find.

There is probably a better solution, which is to tell inkscape how to map "sans-serif" to the appropriate font (e.g., Arial) that PlantUML uses by default. But I couldn't find that answer. It may be a bug in Windows' inkscape; it may be a feature that is missing. I think I didn't have this problem under Windows 7, perhaps because of the default fonts and the way inkscape chose to select the equivalent for "sans-serif". My Windows 8.1 machine has font called 8514fix and 8514oem that appear similar to the Lucida Sans, and are at the top of the font list. I'd guess that inkscape is picking one for its equivalent of "sans-serif" but PlantUML is using another. Your mileage may vary. See this and this for more hints.

Configuring LyX for PlantUML -> SVG -> PDF

If you activate PlantUML -> PNG and/or PlantUML -> EPS, when you generate PDF files, LyX might use one of those intermediate formats, which means you'll lose the fidelity of the diagram in the PDF conversion.

For this reason, I only enabled the PlantUML -> SVG converter inside of LyX. That means I deleted the PlantUML -> PNG and PlantUML -> EPS converters mentioned in the answer by Rajender. The single PlantUML -> SVG converter I use looks as follows:

PlantUML to SVG converter in LyX

Note the command as follows:

plantuml.bat -tsvg -charset UTF-8 $$i $$o
  • plantuml.bat is the batch file described by Rajender
  • -tsvg tells PlantUML to convert to SVG
  • -charset UTF-8 is important under Windows if you're using foreign language characters (accents, etc.) in the .plantuml source file, especially if you're sharing it with people on other systems. The default encoding in Windows PlantUML is not UTF-8.

To get the SVG to PDF, there's a converter that should automatically be there when LyX finds inkscape during its Reconfigure command mentioned above. But verify the settings as below. If inkscape is not installed, you'll get all kinds of weird errors and LyX will try to convert SVG to .ppm (at least on my Windows 8.1 system, that was what was happening).

SVG to PDF converter in LyX

The SVG -> PDF conversion command using inkscape is as follows. It very straightforward:

inkscape --file=$$i --export-area-drawing --without-gui --export-pdf=$$o


Here's a final result with the following PlantUML code saved as UseCase.plantuml and inserted into a LyX document with Insert > Graphics:

skinparam style strictuml
skinparam handwritten true
' the font below is installed on Windows, may not work on other systems
skinparam defaultFontName Segoe Print
left to right direction
skinparam packageStyle rect
actor Customer as C
actor "Credit\nAuthorization\nService" as CA
rectangle "Bike Rental System" {
  (Process\nMembership) as (PM)
  (Borrow Bike) as (BB)
  (Return Bike) as (RB)
  (Request\nExtension) as (RE)
  (Request New\nAccess Code) as (NC)
  C -- (PM)
  PM -- CA
  C -- (BB)
  C -- (RB)
  C -- (RE)
  C -- (NC)

Here's what it looks like in Adobe Acrobat. Note that the PlantUML text is PDF text (see the selection):

enter image description here

Viewing PlantUML errors (in Windows)

I followed Rajender's excellent explanation on how to do a batch file for windows to convert PlantUML files inside of LyX. There is one troubling problem: if you have syntax errors in your PlantUML file, the conversion fails and LyX only complains with an Error converting to loadable format.

The solution I found in Windows is to:

  • enable the PlantUML -> PNG converter (discussed above). The syntax errors only appear in the .PNG images, not .SVG.
  • prevent the PlantUML.bat file from returning a failure (so LyX thinks the conversion completed successfully). This can be done by adding some lines to catch the %ERRORLEVEL%:

    java -jar "%~dp0plantuml.jar" %*
    set exitcode = %ERRORLEVEL%
    echo %exitcode%

Actually, you can probably just put echo "hello" after the java command to cause the .bat file to succeed always.

As such, errors will appear in the PNG like this:

PlantUML errors inside PNG image in LyX


Here is the info I got from Rainer, and using his help I am able to display included .plantuml files.

Help to configure lyx with plantUML

A summary of the steps follows:

  • Install PlantUML (and GraphViz which it requires)
  • Create a script (e.g., plantuml.bat on Windows)so that PlantUML can be run from a command line to create SVG files. Make sure it works properly by testing it manually, as LyX won't reveal easily any problems.
  • Make sure LyX has in its PATH settings the directory of the script in the previous step, per this: Configuring the PATH in LyX to find the PlantUML command script
  • Set up LyX to recognize PlantUML text files (.plantuml) as a new format, per this: Configuring the PlantUML file format in LyX
  • Set up LyX to convert these files to SVG, using the script created above, per this: Configuring the conversion of PlantUML to SVG in LyX Note: To support non-ascii characters in the PlantUML, you need to specify the following: plantuml.bat -tsvg -charset UTF-8 $$i $$o
  • Insert a PlantUML diagram (e.g., MyDiagram.plantuml) using Insert > Graphics: Inserting a PlantUML diagram
    LyX should convert the image to something visible on the screen. If it does not work, you may need to validate your SVG conversion settings in LyX, including SVG -> PNG and SVG -> PDF (Graphics) which should probably be done with an inkscape command in the LyX Converters setting. In Windows, I had to use the LyX Tools > Reconfigure feature to get it to recognize the latest version of Inkscape for the SVG conversions to work properly. You also have to restart LyX after you run that feature.
  • Once the image is in LyX, you can edit the .plantuml source code with an external editor by right-clicking on the image and choosing Edit Externally...: Opening the .plantuml source via external editor in LyX
  • In LyX under Windows, you can set up the .plantuml format to be edited by Notepad++ (or your favorite editor): Configuring the custom editor in LyX for PlantUML files

Hope this helps.

  • 1
    Good solution, is it possible to write plantuml code into LyX document directly and do convert in background.
    – Beatlej
    Sep 3, 2014 at 21:01
  • I was able to get it to work under Windows, but it took a (much too) long time. The configuration with Java, PlantUML, GraphViz and lyx is very complex. Make sure you can get the .bat file working from the command line first, then make sure it is integrated into lyx. Jul 3, 2015 at 0:32
  • @Beatlej I wonder if it can be done by using Child documents in LyX? The problem is that the source code might also appear in your LyX document (not just the diagram). Jun 23, 2016 at 14:31
  • With newer versions of plantuml it looks like it is needed to modify the converter command a little bit, because now there is no way to set the output file name in plantuml. So, instead of plantuml.bat -tsvg $$i $$o you should use plantuml.bat -tsvg $$i Jul 2, 2019 at 9:06
  • Indeed, @VladimirLebedev -- otherwise, one gets an exception IllegalArgumentException due to the output file from $$o - thanks for that hint. Oct 13, 2019 at 3:58

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.