Blueprint template lookup not documented enough #266

mitsuhiko opened this Issue Jun 28, 2011 · 12 comments


None yet

mitsuhiko commented Jun 28, 2011

The new blueprint template lookup scheme where the templates folder is just added to the searchpath instead of doing some weird stuff with the names as before. The documentation has to be clearer about that.

@ghost ghost assigned rduplain Jun 28, 2011


garbados commented Mar 12, 2012

When you say documentation, do you mean docstrings in the source and the like, or docs/blueprints.rst? What about them do you wish was clearer?


rduplain commented Mar 13, 2012

This is fixed.

The template folder is added to the searchpath of templates but with a lower priority than the actual application’s template folder. That way you can easily override templates that a blueprint provides in the actual application.

@rduplain rduplain closed this Mar 13, 2012


rduplain commented Aug 3, 2013

So if you have a blueprint in the folder yourapplication/admin and you want to render the template 'admin/index.html' and you have provided templates as a template_folder you will have to create a file like this: yourapplication/admin/templates/admin/index.html.

rturk commented Dec 13, 2013

This still confusing. Can you add some examples in the documentation?

The current documentation ( is still confusing. It should state that the reason we have to render 'admin/index.html' instead of 'index.html' is to avoid name conflict.

However, I would consider a bug.

aguegu commented Aug 26, 2014

@rduplain I have been struggling with this BUG for an hour. And It is so not a feature. At least, there should be some argument could be set to make the higher priority of template_folder.

PS. How to print the current searchpath of templates?


untitaker commented Aug 26, 2014

Reopening because of doc issues.

@untitaker untitaker reopened this Aug 26, 2014

veonua commented Jan 10, 2016

it's a BUG.
template renderer must not use other's blueprint template folder to make a page.
it makes no sense to duplicate name of blueprint in template subfolder,
I've made separated blueprints to handle index pages separately


ThiefMaster commented Jan 10, 2016

It is not a bug per se.

But it does depend a lot on how your application is structured whether it is useful or not - in my opinon it's not useful in most cases and having the blueprint name automatically included in the template folder would make sense.

Luckily you can easily implement this for yourself in an even more flexible way than just using the blueprint name. You can find an example here (the virtual_template_folder code).

(I wouldn't mind to have an option for this in Flask itself, since that way IDEs like PyCharm would be likely to support it instead of not being able to show me a link to edit the template a view function is rendering)

Trii commented Jan 26, 2016

I'm running into the same issue as It makes sense to be able to override a blueprint's template in the main template folder, but rendering another blueprint's template due to the template search path order seems buggy to me.

Using the facebook example from
If I were to render my templates in the blueprint using render_template('profile/layout.html'), then how would I override that template in the root templates folder?

I just ran into this issue today - not the documentation issue posted by OP, but the one referred to in the stackoverflow question linked to above, and discussed later on in these comments. I agree with @Trii - overriding a blueprint's template from below it on the tree makes sense, but it seems wrong that templates from different blueprints conflict with each other. When you're loading a template with render_template from within a blueprint, why would the other blueprints' templates folder be included from the search path? Is it useful to be able to override a blueprint's templates from another blueprint?

Reading and thinking more, I think I've figured out how it works: there is a global namespace for templates, and each blueprint's templates folder is at the root of that namespace. It's a simple system, which is nice, but it means that if you want to have your templates in their own namespace, you have to put them in a subfolder whose name is unique to the blueprint. In practice you use the name of the blueprint. I guess that's not that bad - the structure of most ruby gems are like this, for example, with Foo::Bar::Baz being in the file foo/bar/baz.rb. If your are creating a blueprint named admin, you only have to move your templates one folder deeper, from admin/templates/ to admin/templates/admin/. For the cases that I've run into so far, it would be more intuitive to have files in admin/templates just be assumed to be in their own admin namespace already. But it's not too big a deal.

The bigger issue is that, in order to refer to a template for your blueprint under this system, you have to use the template's global name (admin/home.html in this case). This means a lot of repetition of the blueprint name in files inside the blueprint, from render_template calls in python, to include and extends tags in jinja. It would be nice if we could avoid all that repetition.

RaHus added a commit to RaHus/flask that referenced this issue Jun 1, 2016

Mention the template name conflict issue in docs.
In the blueprints templates documentation mention
the possible templates name conflict issue
re #266

davidism added a commit that referenced this issue Jun 4, 2016

Mention the template name conflict issue in blueprint templates docs (#…

* Mention the template name conflict issue in docs.
In the blueprints templates documentation mention
the possible templates name conflict issue
re #266

* Mention priorities between blueprints
and other rephrasing fixes

@davidism davidism closed this Jun 4, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment