c++ c++-faq templates undefined-reference

Why can templates only be implemented in the header file?


Quote from The C++ standard library: a tutorial and handbook:

The only portable way of using templates at the moment is to implement them in header files by using inline functions.

Why is this?

(Clarification: header files are not the only portable solution. But they are the most convenient portable solution.)


  • 24

    While it is true that placing all template function definitions into the header file is probably the most convenient way to use them, it is still not clear what’s “inline” doing in that quote. There’s no need to use inline functions for that. “Inline” has absolutely nothing to do with this.

    Sep 18, 2014 at 4:11

  • 14

    Book is out of date.

    – gerardw

    Oct 11, 2014 at 13:25

  • 13

    A template is not like a function which can be compiled into byte code. It is just a pattern to generate such a function. If you put a template on its own into a *.cpp file, there is nothing to compile. Moreover, the explicite instanciation is actually not a template, but the starting point to make a function out of the template which ends up in the *.obj file.

    – dgrat

    May 28, 2019 at 9:02

  • 36

    Am I the only one who feels that the template concept is crippled in C++ due to this?…

    Dec 9, 2019 at 21:39

  • 2

    @AnT perhaps they meant “inline” not as the keyword but rather as “methods implemented at the place of declaration, inside the class”.

    – Vorac

    Feb 13 at 23:12


Caveat: It is not necessary to put the implementation in the header file, see the alternative solution at the end of this answer.

Anyway, the reason your code is failing is that, when instantiating a template, the compiler creates a new class with the given template argument. For example:

template<typename T>
struct Foo
    T bar;
    void doSomething(T param) {/* do stuff using T */}

// somewhere in a .cpp
Foo<int> f; 

When reading this line, the compiler will create a new class (let’s call it FooInt), which is equivalent to the following:

struct FooInt
    int bar;
    void doSomething(int param) {/* do stuff using int */}

Consequently, the compiler needs to have access to the implementation of the methods, to instantiate them with the template argument (in this case int). If these implementations were not in the header, they wouldn’t be accessible, and therefore the compiler wouldn’t be able to instantiate the template.

A common solution to this is to write the template declaration in a header file, then implement the class in an implementation file (for example .tpp), and include this implementation file at the end of the header.


template <typename T>
struct Foo
    void doSomething(T param);

#include "Foo.tpp"


template <typename T>
void Foo<T>::doSomething(T param)

This way, implementation is still separated from declaration, but is accessible to the compiler.

Alternative solution

Another solution is to keep the implementation separated, and explicitly instantiate all the template instances you’ll need:


// no implementation
template <typename T> struct Foo { ... };


// implementation of Foo's methods

// explicit instantiations
template class Foo<int>;
template class Foo<float>;
// You will only be able to use Foo with int or float

If my explanation isn’t clear enough, you can have a look at the C++ Super-FAQ on this subject.


  • 114

    Actually the explicit instantiation needs to be in a .cpp file which has access to the definitions for all of Foo’s member functions, rather than in the header.

    – Mankarse

    May 28, 2011 at 10:21

  • 15

    “the compiler needs to have access to the implementation of the methods, to instantiate them with the template argument (in this case int). If these implementations were not in the header, they wouldn’t be accessible” But why is an implementation in the .cpp file not accessible to the compiler? A compiler can also access .cpp information, how else would it turn them into .obj files? EDIT: answer to this question is in the link provided in this answer…

    – xcrypt

    Jan 14, 2012 at 23:56

  • 41

    I don’t think this explains the question that clearly, the key thing is obviously related with the compilation UNIT which is not mentioned in this post

    – zinking

    Aug 23, 2012 at 9:47

  • 6

    @Gabson: structs and classes are equivalent with the exception that the default access modifier for classes is “private”, while it is public for structs. There are some other tiny differences that you can learn by looking at this question.

    Feb 21, 2014 at 14:12

  • 4

    I’ve added a sentence at the very start of this answer to clarify that the question is based on a false premise. If somebody asks “Why is X true?” when in fact X is not true, we should quickly reject that assumption.

    Aug 5, 2015 at 9:39


It’s because of the requirement for separate compilation and because templates are instantiation-style polymorphism.

Lets get a little closer to concrete for an explanation. Say I’ve got the following files:

  • foo.h
    • declares the interface of class MyClass<T>
  • foo.cpp
    • defines the implementation of class MyClass<T>
  • bar.cpp
    • uses MyClass<int>

Separate compilation means I should be able to compile foo.cpp independently from bar.cpp. The compiler does all the hard work of analysis, optimization, and code generation on each compilation unit completely independently; we don’t need to do whole-program analysis. It’s only the linker that needs to handle the entire program at once, and the linker’s job is substantially easier.

bar.cpp doesn’t even need to exist when I compile foo.cpp, but I should still be able to link the foo.o I already had together with the bar.o I’ve only just produced, without needing to recompile foo.cpp. foo.cpp could even be compiled into a dynamic library, distributed somewhere else without foo.cpp, and linked with code they write years after I wrote foo.cpp.

“Instantiation-style polymorphism” means that the template MyClass<T> isn’t really a generic class that can be compiled to code that can work for any value of T. That would add overhead such as boxing, needing to pass function pointers to allocators and constructors, etc. The intention of C++ templates is to avoid having to write nearly identical class MyClass_int, class MyClass_float, etc, but to still be able to end up with compiled code that is mostly as if we had written each version separately. So a template is literally a template; a class template is not a class, it’s a recipe for creating a new class for each T we encounter. A template cannot be compiled into code, only the result of instantiating the template can be compiled.

So when foo.cpp is compiled, the compiler can’t see bar.cpp to know that MyClass<int> is needed. It can see the template MyClass<T>, but it can’t emit code for that (it’s a template, not a class). And when bar.cpp is compiled, the compiler can see that it needs to create a MyClass<int>, but it can’t see the template MyClass<T> (only its interface in foo.h) so it can’t create it.

If foo.cpp itself uses MyClass<int>, then code for that will be generated while compiling foo.cpp, so when bar.o is linked to foo.o they can be hooked up and will work. We can use that fact to allow a finite set of template instantiations to be implemented in a .cpp file by writing a single template. But there’s no way for bar.cpp to use the template as a template and instantiate it on whatever types it likes; it can only use pre-existing versions of the templated class that the author of foo.cpp thought to provide.

You might think that when compiling a template the compiler should “generate all versions”, with the ones that are never used being filtered out during linking. Aside from the huge overhead and the extreme difficulties such an approach would face because “type modifier” features like pointers and arrays allow even just the built-in types to give rise to an infinite number of types, what happens when I now extend my program by adding:

  • baz.cpp
    • declares and implements class BazPrivate, and uses MyClass<BazPrivate>

There is no possible way that this could work unless we either

  1. Have to recompile foo.cpp every time we change any other file in the program, in case it added a new novel instantiation of MyClass<T>
  2. Require that baz.cpp contains (possibly via header includes) the full template of MyClass<T>, so that the compiler can generate MyClass<BazPrivate> during compilation of baz.cpp.

Nobody likes (1), because whole-program-analysis compilation systems take forever to compile , and because it makes it impossible to distribute compiled libraries without the source code. So we have (2) instead.


  • 71

    emphasized quote a template is literally a template; a class template is not a class, it’s a recipe for creating a new class for each T we encounter

    – v.oddou

    Apr 25, 2016 at 9:57

  • 1

    @Birger You should be able to do it from any file that has access to the full template implementation (either because it’s in the same file or via header includes).

    – Ben

    Mar 9, 2017 at 11:02

  • 17

    @ajeh It’s not rhetoric. The question is “why do you have to implement templates in a header?”, so I explained the technical choices the C++ language makes that lead to this requirement. Before I wrote my answer others already provided workarounds that are not full solutions, because there can’t be a full solution. I felt those answers would be complemented by a fuller discussion of the “why” angle of the question.

    – Ben

    Apr 2, 2018 at 22:02

  • 1

    imagine it this way folks… if you weren’t using templates (to efficiently code what you needed), you’d only be offering a few versions of that class anyway. so you have 3 options. 1). don’t use templates. (like all other classes/functions, nobody cares that others can’t alter the types) 2). use templates, and document which types they can use. 3). give them the whole implementation (source) bonus 4). give them the whole source in case they want to make a template from another one of your classes 😉

    – Puddle

    Nov 27, 2018 at 0:01

  • 3

    @VoB Yes, a .tpp file in that sense is just a naming convention for a kind of header file. A “header file” isn’t something specific to the C++ compiler, it’s just what we call a file that we intend to include into other compilation units by using #include. If it helps you work with your code to have template implementations in a separate file from the one that describes the interface of a .cpp file, and to give those template implementation files a specific extension like .tpp, then go for it! The compiler doesn’t know or care about the difference, but it can help humans.

    – Ben

    Jan 23, 2021 at 0:03


Plenty correct answers here, but I wanted to add this (for completeness):

If you, at the bottom of the implementation cpp file, do explicit instantiation of all the types the template will be used with, the linker will be able to find them as usual.

Edit: Adding example of explicit template instantiation. Used after the template has been defined, and all member functions has been defined.

template class vector<int>;

This will instantiate (and thus make available to the linker) the class and all its member functions (only). Similar syntax works for function templates, so if you have non-member operator overloads you may need to do the same for those.

The above example is fairly useless since vector is fully defined in headers, except when a common include file (precompiled header?) uses extern template class vector<int> so as to keep it from instantiating it in all the other (1000?) files that use vector.


  • 72

    Ugh. Good answer, but no real clean solution. Listing out all possible types for a template does not seem to go with what a template is supposed to be.

    – Jiminion

    Jul 17, 2014 at 17:49

  • 8

    This can be good in many cases but generally breaks the purpose of template which is meant to allow you to use the class with any type without manually listing them.

    Dec 9, 2014 at 3:27

  • 10

    vector is not a good example because a container is inherently targeting “all” types. But it does happen very frequently that you create templates that are only meant for a specific set of types, for instance numeric types: int8_t, int16_t, int32_t, uint8_t, uint16_t, etc. In this case, it still makes sense to use a template, but explicitly instantiating them for the whole set of types is also possible and, in my opinion, recommended.

    – UncleZeiv

    Jun 3, 2015 at 15:41

  • Used after the template has been defined, “and all member functions has been defined”. Thanks !

    – Vitt Volt

    Feb 16, 2017 at 6:04

  • 1

    I feel like I’m missing something … I put the explicit instantiation for two types into the class’s .cpp file and the two instantiations are referred to from other .cpp files, and I still get the linking error that the members are not found.

    – oarfish

    Sep 4, 2019 at 14:38