Nbdev for use with production code

Hi @jeremy , thank you for all of your excellent work with fastai and nbdev! I’ve found coding with nbdev to be a great improvement to my productivity and code documentation.

However, I’ve recently been told by some ML Engineering hiring managers that having nbdev (and Jupyter notebooks) at the forefront of my Github repos suggests that I don’t know how to write production quality code since I’m relying on a framework. I would love to hear your thoughts on this and if I should be proving them wrong or branching away from nbdev for more projects.


Using nbdev is equivalent to using another programming language. It’s a different way of programming, and it isn’t useful to judge it according to “mainstream python standards”. It’s worth thinking about what “production quality” means. To me, it means: (1) excellent test coverage w/automated tests (2) documentation, (3) and maintainability.

Arguably, nbdev facilitates higher quality software on average because it encourages more tests and more documentation. However there is some friction to using nbdev on a team of traditional python developers:

Understanding The Friction of nbdev:

  • It’s a new programming language (fastcore + the nbdev workflow), so you have to convince everyone you are working with to use this new programming language. This is the best way of framing it because it is very often misunderstood as being “ameuter way of writing python code” just b/c it has notebooks, which is incorrect. Convincing the rest of your teammates to learn a new programming language is not easy. They may argue with you that learning a new programming language is not a good use of their time. You can argue that nbdev makes you much more productive, and is better for the task at hand, but it can be incredibly hard, even futile, to convince devs to learn a new programming language/workflow. Software engineers love to fight about the best programming language all the time, and many regard it as a waste of time. Basically you have to assess if convincing people to learn another programming language is worth your time and if it is possible. You also have to understand nbdev enough to defend it and understand its philosophy and capabilities.
  • Because it is a new programming language/workflow, it may not fit nicely into the rest of the development tool stack at some companies. For example, while you can facilitate Code Review of notebooks with ReviewNB, you have to sacrifice some of the full code review functionality like suggest changes, etc. There might be other idiosyncratic tools in your corporate environment that might also clash with the use of nbdev. You should assess how much of an issue this is for you.

If you aren’t able to convince your team to learn nbdev, its’ going to detract from maintainability (point #3). However, I think its possible to convicne people (see next section):

How to drive adoption of nbdev.

The best way to drive adoption of nbdev (I’ve done it at several companies) is to prodcue lots useful small tools with it that are helpful to many people. For example, this nbdev project creates a small CLI that converts word press articles to markdown, or this CLI that analyzes markdown documents for SEO.

I would stay away from philisophical arguments as much as possible and make small tools and share them with people. People will be amazed by the documentation and polish, and genuinely be thankful for these tools. I find that this has the best chance of winning people over.

Hope that helps. You can also see this 15 minute talk to get an idea of how I present nbdev to developers who are not familiar with it.

Analogy With Lisp / Paul Graham

If you listen carefully to how core maintainers talk about nbdev, it is very similar to the way Paul Graham talks about Lisp as “a secret weapon”. In fact, that exactly how we describe it in this blog post “nbdev+Quarto: A new secret weapon for productivity”!

In his essay, Paul Graham feels so strongly about Lisp that he thinks it is a central component of his competitive advantage of startups he has founded. We feel the same about nbdev! However, we hope that nbdev has the opportunity for more adoption because its very tractable to learn for people who are familiar with python, which by many accounts is one of the most popular programming languages in use today.

Did Paul Graham convince the world to learn Lisp? Clearly not – but Paul wasn’t trying to convince the world to learn Lisp, he was pointing out that one of the advantages of being a small startup is that you can choose what tools you want, even if those tools stray from conventional practices. This is interesting, because I feel like nbdev is in a similar situation. I suspect that the best chances of gaining adoption of nbdev is on small teams, startups and other places where people are willing to think outside the box. It might be an uphill battle or even a bad idea to try to deploy nbdev in large corporations who are already set in their ways. While we have seen bigger companies like Netlfix willing to think outside the box (see these testiominals), I believe these are special cases where teams have already been thinking differently about their development worklfow, and have thus been open to using nbdev.

Either way, I suggest reading Paul’s essay[1] for a possible framework in which you might think about nbdev as well!

cc: @seem @jeremy

  1. Paul doesn’t have https enabled on his site. Just ignore this as its just a static site, so its fine. ↩︎


Thanks Hamel! That’s a useful framework to help explain why I would use nbdev, and I think I have a better understanding of the philosophy now. If programming is a race, nbdev is like a better pair of running shoes, not a crutch. I’ll just send a link to your response here if people question me on using nbdev in the future :stuck_out_tongue:

1 Like

Thanks @hamelsmu. This is a very moving post. I’m in a early startup and even then it was difficult to adapt it across the teams. I appreciate the focus on building small useful tools to propel the adoption of nbdev ecosystem.

1 Like

I am a CTO of a company that have used nbdev in production for 3 years now. We did tweak the documentation generation a bit to work with mkdocs (GitHub - airtai/nbdev-mkdocs: Extension to nbdev for usage of Material for Mkdocs instead of Quarto), but that’s about it. You can see an example of one open-source project using it, but we have a number of proprietary ones built and deployed with the same pipeline:


seems a paradox to be the “pointy-haired boss” to convince my team to use Nbdev