Introducing django-browser-reload: Automatically Reload Your Browser in Development

Round and round we reload.

Update (2021-01-07): My new book Boost Your Django DX covers django-browser-reload in its chapter on the development server.

Hitting “refresh” to see your changes is an instinct many web developers develop. But it’s a small waste of time that adds up to many hours per year spent waiting. It’s a sub-optimal development experience (DX).

Django’s development server reloads itself when you change code, but it does not tell the browser to reload. And it does not do anything when a template or static asset changes.

Framework-Agnostic Tools

There various framework-agnostic tools out there to address these shortcomings, but I’ve often found they have shortcomings. For a start, they’re an extra thing to install, normally in a different language, requiring e.g. Node.js to be set up. And they normally wrap the server, so you have to run both the tool and Django’s runserver.

Perhaps the biggest potential drawback of such reloaders is that they watch project files a second time, whilst Django is already watching them. This can take a lot of CPU if done without OS-specific APIs (Django can do that with Watchman, which you should definitely set up).


Whilst I’m working on my upcoming Django DX book, I have thought about this problem on-and-off. I came up with an idea for a browser reloader that could use Django’s existing file watching, without extra dependencies. Yesterday I finished the first iteration and released it as django-browser-reload. Hooray!

Whenever you edit a template, or make a code change that restarts the server, django-browser-reload reloads the current page. If you open multiple tabs, only the most recently one will reload, to avoid a thundering herd.

I enjoyed putting this package together. I had to dive back into JavaScript in order to make use of the new (to me) EventSource and SharedWorker APIs. I covered the final structure in the README’s “How It Works” Guide. It should be possible to adapt the technique to other web frameworks.

Please install django-browser-reload and try it out! I’d like to know what breaks, or is missing. There are some features yet to do - reloading on static asset changes, and working with Jinja templates. But it should already be good enough to save you a bunch of time.


May this save you many a second in development,


Improve your Django develompent experience with my new book.

Subscribe via RSS, Twitter, Mastodon, or email:

One summary email a week, no spam, I pinky promise.

Related posts: