What makes the Django web framework hard to learn?

I’ve given this question a lot of thought recently. As the author of Django for Beginners, I receive regular feedback from readers– both total beginners and those experienced in other programming languages but new to Django–who are struggling. I’m very empathetic since I first learned web development back in 2013 with Django and it was not a smooth road at all.

So what is it? The Django community is very open and collaborative. The official documentation is exceptionally comprehensive. And it’s all written in Python, now the most popular introductory programming language at U.S. universities and the second most popular language on Github behind only JavaScript.

Why would someone even consider a framework like Ruby on Rails which entails learning a totally new programming language that has little usage outside web development?

Here are Django’s positives in my opinion:

And here are some possible reasons why Django is challenging to learn:

No 1: Lack of beginner-friendly tutorials

Why isn’t there a comprehensive resource like the Rails Tutorial available? One that baby-steps through building a simple CRUD application with user accounts and deployment? If it exists, I’m unaware of it.

Most tutorials and books seem firmly aimed at intermediate/advanced programmers, even the official polls tutorial. By contrast, most Ruby on Rails and JavaScript tutorials seem aimed at beginners. Why not Django?

Is it because the average Python programmer is more experienced? Or assumed to be? I genuinely don’t know why.

No 2: Relatively complicated “Hello, World”

Compared with Flask or Express, creating a simple “Hello, World” takes more work in Django. You need to correctly install Python 3, virtual environments, create a new Django project, a new app, and then install urls at both the project and app level, plus create a view in the app. It’s a lot.

If you’re an experienced Django developer, yes, you don’t have to create an app for a “Hello, World” example, but since the project/app paradigm is used throughout Django it’s less confusing to beginners to just start with this approach.

No 3: Local development setup

Back in 2016 I taught a college-level class on web development with MeteorJS. It succeeded in large part because Meteor had a one-line installation that provided a full working local dev environment with a configured MongoDB database, and default plugins for user auth among other things. Plus, it was all written in JavaScript. By the end of three short weeks, students had built surprisingly complex web applications.

Django (and most other frameworks) by contrast can be difficult for a beginner to setup. You must install Python 3. Then install and configure virtual environments. Then install Django. And really you should also download and configure a local database like Postgres rather than the built-in SQLite. It’s a lot.

No 4: Multiple ways to do the same thing

Django gives developers a lot of flexibility when it comes to structuring a new project. This is a double-edged sword: I speak from experience when I say it is deeply confusing to read multiple different approaches to basic project setup, let alone more complex cases.

As an example, consider the official polls tutorial which advocates including templates in an app -> templates -> app -> template_name.html format, which is how the Django loader looks by default. That’s fine, but then most real-world projects advocate tweaking your settings.py file and putting all your templates in one project-level templates folder. Or putting project-level templates there but including app-level templates in the app directories.

No 5: Function-based views vs Class-based views

Class-based views are in my opinion a big improvement in Django and seem to be the way things are headed. However…it’s really confusing to have tutorials switch between the two, yet this seems to be the normal way Django is presented (see the previous point on Multiple ways to do the same thing). As in, here’s the “real” way to do it with functions and here’s the CBV shortcut.

I understand why showing both approaches increases understanding once you’re at a given level. But I think focusing on how simple things can be with CBV is a better up-front approach. Use CBVs and even better Generic Class Based Views to show how little code we need to build common functionality. Then, once the reader has gotten it to work and has some confidence, go deeper with the function-based approach or show how to customize the CBVs. Most tutorials do this backwards.

No 6: The Urls, Views, Templates dance

It takes a lot of practice to become used to updating three separate files for a single new page on your site. It’s not always obvious where names or arguments in a URL map to a view, let alone how to properly display them in a template. In particular, once you start doing detail views, things get hairy for beginners in a hurry.

Concluding Thoughts

I’ll add to this post over time but for now these are my main thoughts. And to be clear, I’m writing this because I think Python and Django are fantastic and I want to figure out how to share that with more programmers.

To that end, if you’d like a step-by-step guide to Django, starting with proper setup, Hello World, and progressing from there through multiple web applications, please check out Django For Beginners. I focus on how to build things in the simplest way possible and then dive into deeper discussions of what’s going on under-the-hood. I think ultimately the answer to my question is better beginner-friendly instruction.