Ipydrawio: diagrams in JupyterLab... with pages, layers, widgets, PDF export

Hey folks, it’s been mentioned/demoed a few times, but I wanted to point out the latest (and in some sense, first) release of ipydrawio, which reads and edits multi-page, multi-layer drawio drawings in JupyterLab 3, with a few Jupyter-specific suprises. Today, ipydrawio 1.0.1 is readily-installable from pip, conda (watch out! its 40-70mb!) and ready-to-try on binder with all the fixin’s. It looks something like…


What’s it do?

  • reuse all the drawio templates, shapes, configuration options, and UI themes, even offline
  • opens and saves editable drawio/mxgraph .xml, .png, .svg in JupyterLab 3 that work on diagrams.net, confluence, etc.
    • also reads/writes to .ipynb metadata… but nothing else reads it :blush:
      • and it’s a Jupyter Widget!
      • and a MIME renderer!
    • with the companion ipydrawio-export, also generates .pdf
      • warning: yep, another headless browser thing that needs nodejs. but i didn’t have to write it :man_shrugging:

How’d we get here?

The good folks at QuantStack/jupyterlab-drawio got the ball rolling with drawio in Jupyter, and have been keeping the lights on (it recently got JupyterLab 3 support) but we had some… ambitions. What is now ipydrawio started as a couple pull requests to support features for demos, but eventually kinda had to stand on its own, though under the same name, in hopes we could unify the code bases again. Welp, that didn’t happen. :blush:

When JupyterLab 3 came out, it became much more possible to distribute (all those shapes, whew!)… webpack would just crash, etc. It’s taken a while, but we’re in a much more fun place now!

Where to next?

Aside from the usual (more docs, more tests), stuff we’ve thought of: make it work with other extensions like jupyter-videochat and jupyterlab-lsp, doing some Jupyter mockup templates, and closer integration with Notebook rich displays. Come on by GitHub if there’s more we can do together to make computational diagramming fun in Jupyter!


Via here, some of the drawio extensions provide mechanisms for scripting the creating of particular diagrams. For example, create draw.io diagrams from csv files. You can also use PlantUML to generate draw.i diagrams.

One of the ways I try to maximise generative reuse potential in notebooks is to script diagrams using things like blockdiag magics.

It would be really interesting to explore how scripted diagrams could be defined in notebook magic cells and then used to generate images within or via drawio.

1 Like

Yeah… to the extent possible, the code tries not to interact too closely with any API other than what is exposed by the IFrame embed API. Documentation of the full drawio is… sparse.

The PlantUML thing needs a server, and no doubt there is a configuration flange, sprocket, etc. to set the URL. However, as a bit of a diagram snob, I’ve never liked how the plantuml stuff actually looks at the end without a lot of tweaking, so I personally won’t be rushing to get that working any time soon, though it would be entirely possible with the extension API.

The XML format, on the other hand, is very robust (if also not particularly documented). On the kernel side, the direction I am interested in is building it, such as with graphviz2drawio.

Re: trying to just stick to the embed APi, ok, makes sense.

The graphviz2drawio uses XML and the filesystem, I guess, so you can “drive” image creation in drawio that way; I guess I always hankered after the idea of an API to the drawio drawing engine that I could just pass scripts to and get layed out diagrams back, with an option to also drop into the editor if required (though again for reuse my preference is that the script, and maybe a style file, is complete enough to render the diagram you want).

That’s awesome we are using draw.io + Jupyter to mindmap all our processes at www.naas.ai! Thank you :+1:

1 Like

@bollwyvl that looks really cool! A colleague of mine saw drawio and immediately asked me whether collaborative drawing would be also feasible. Do you think it would be possible to combine it with
the real-time collaboration version of JupyterLab with little extra effort?

1 Like

little extra effort

PRs welcome from your colleague, but :laughing: yeah, naw, it’s not going to be “little.” Diagram editing has all the complexity of the notebook, plus multiple pages, multiple layers, wysiwyg, etc. Unless it plugs seamlessly into the drawio file sync stuff, yeah, well…

The first thing I see spending effort on is, as mentioned, integration with jupyterlab-videochat, as Jitsi has a JSON bus we should be able to put anything on, including the (basically undocumented) file sync mechanism built into drawio, as we would then inherit the trust, video, schreenshare, chat, etc. mechanisms from two production-ready systems rather than having to do them whole cloth or wait for other extensions to exist.

As to something in Lab core: I’m highly unlikely to spend any development time integrating with a pre-release feature, and if it comes to a separate “version”… it might not be something that we can support… but the whole API is basically exposed, so there’s nothing preventing someone from writing an alternate store vs the existing ones (mime, document, jupyter widgets).

1 Like

Thank you very much for your quick assessment!

Update here: 1.1.0 (available on pip and conda-forge) brings a few new features:

sketch theme


This is by far the most minimal UI drawio has offered, and takes up very little screen real estate, especially when full-screened. But only a single page (unless I have missed where to find it). The freehand tool is also fun… but there’s no editing after the fact.

New Custom Diagram… Launcher Item


It was possible to find the various formats, themes, and templates before, but it was really getting to be a lot. This little UI offers selecting an expanding number of options.

There’s some more stuff coming here, as the API is wide open for adding more custom templates… one of the first we’re working on are some reusable JupyterLab UI mockups (note that screen above shows it, but it didn’t quite make the release for the community call :blush:). Not much to look at because… it’s pretty much made directly from the lab UI, including the actual icon SVGs. But hopefully it will be a fun place to imagine new features!


Oh, and there’s a docs site now.


So there’s some heartache with how the sketch theme mangles some of the pre-cooked shapes… I’ve re-opened the discussion about the default theme and would :heart: any insight!


Still haven’t quite gotten the new templates, tutorials, and docs stuff released, but the latest docs site now has a jupyterlite-powered demo.

1 Like

I only recently learned about draw.io integration in JupyterLab and thus about jupyterlab-drawio and ipydrawio, so I’m wondering, is there some sort comparison page or FAQ which might help me decide which to pick? :slight_smile:

First off, and one again, maximum :heart: to my good friends at jupyterlab-drawio!

Both have jupyterlite sites (jupyterlab-drawio is in the examples of jupyterlite) and binders, so you can try them out right now without installation, which, for a drawing program, is probably more indicative than a laundry list.

As to the list… the bullets at the top of this post are the features unique to ipydrawio that were important enough to me and the teams I support to undertake building, testing, packaging, documenting, and working with the jgraph upstream for all this stuff.

The primary implementation distinction is in using a direct, in-DOM embedding of the mxgraph DOM vs use of an iframe for the full drawio UI. The iframe approach introduces some surprises and some redundant UI, but also benefits from the last several years of improvements by the upstream’s flagship product vs. an extension of an example application.

I haven’t been tracking the development of jupyterlab-drawio aside from the work on supporting shared editing, which i plan to blatantly steal with attribution once they work out all the kinks :blush: and JupyterLab 3.1.0 lands.


ipydrawio 1.1.1 is up on pip and conda-forge :tada:!

Aside from a significant bump to drawio 14.9.3, which brings a raft of improvements over 14.7.1, some notables:

  • :broom: jupyter ipydrawio clean can tidy up your diagrams’ XML, which can help in git, etc… it’s still XML, but at least isn’t guaranteed to change its metadata
  • :people_holding_hands: diagrams Just (Kinda) Work with JupyterLab 3.1’s collaborative editing features
  • :bookmark: the docs
    • :construction: have a tutorial which goes through using different diagram templates (including the initial JupyterLab UI mockup set) throughout the lifecycle of designing and building a JupyterLab extension
    • :bulb: have a JupyterLite demo, with optional collaborative editing

Some stuff that didn’t make the cut:

  • :sun_with_face: RetroLab support
  • :balance_scale: Reducing file size
  • :computer_mouse: Awareness/presence of collaborators’ selections
  • :control_knobs: Widget improvements

We hope you have fun drawing things!