A namespace is a named scope that groups related identifiers (functions, classes, variables, constants) so they don't collide with identically named identifiers from other parts of a program. C++98 introduced namespaces to solve a practical problem: once a codebase reaches a few thousand lines, or starts pulling in libraries from different authors, the chance of two files declaring a Cart class or a total() function approaches one. This chapter covers why namespaces exist, how to declare one, how the scope resolution operator :: reaches into them, why std is the namespace encountered first, and how to split a namespace's declarations and definitions across header and source files.

Consider a small e-commerce codebase. Two engineers work in parallel. One writes a checkout module with a Cart class for the shopping cart. The other writes an analytics module with a Cart class for a tracking cart that records browsing events. Both compile fine on their own. The moment a third file tries to #include both headers, the linker (or the compiler, depending on how the headers are written) sees two definitions of Cart in the same scope and refuses to continue.

This is the name collision problem. It has nothing to do with bad code on either side. Both authors picked the obvious name for their concept. The language gives no way to say "my Cart belongs to checkout, theirs belongs to analytics" unless something separates the scopes.

Namespaces provide that separation. Wrap each module's declarations in a named scope and the names stop colliding, because the full identifier becomes checkout::Cart and analytics::Cart, which are clearly two different things.

Both Cart types live in the same program, in the same translation unit even, without any conflict. The compiler treats checkout::Cart and analytics::Cart as completely unrelated types. They have different sizes, different members, and one can't be assigned to the other. The name Cart on its own is ambiguous, but the language never asks for the bare name once the types live inside namespaces. The qualified name always says which one is meant.

Library authors lean on namespaces hard. Boost wraps everything in boost::. The standard library wraps everything in std::. The fmt library wraps everything in fmt::. Even if three of those libraries shipped a vector class, code could still use all three side by side, because the namespaces keep them apart.

A namespace declaration is the keyword namespace, a name, and a block containing whatever declarations belong together:

Anything inside the braces lives in the inventory namespace. From outside, reach it by writing inventory::stockCount, inventory::isInStock(...), or inventory::Product. From inside the same namespace block, the names are unqualified: isInStock can call other functions in inventory by their short name without inventory:: first, because the compiler is already looking in that scope.

There's no semicolon after the closing brace of a namespace. This is different from class and struct, where the trailing semicolon is mandatory. The grammar treats namespaces as more like enclosing blocks than declarations.

Namespace names follow the same rules as any other identifier: letters, digits, underscores, no leading digit, no reserved words. The convention in modern C++ codebases is lowercase, sometimes with underscores (shop, order_processing), to keep them visually distinct from class names, which are usually capitalised. The standard library uses lowercase (std, std::chrono, std::filesystem), and most third-party libraries follow suit.

A full executable example. The pricing namespace holds a constant and a helper, and main reaches into it using the scope resolution operator:

The constant taxRate and the function withTax are both members of pricing. From inside the namespace, withTax uses taxRate directly. From outside, in main, both names need the pricing:: prefix to be visible.

A namespace can hold any kind of declaration that a global scope can hold: functions, variables, constants, classes, structs, enums, type aliases, templates, even nested namespaces. What it cannot hold is statements. A for loop or an if can't sit directly inside a namespace block, the same way it can't sit directly at file scope. Namespaces are about names, not execution.

The :: operator says "the thing called X that lives inside scope Y". Read pricing::withTax as "the withTax in pricing". The left side is the scope, the right side is the name.

It's the same operator that appears in two other places:

In all three cases, :: asks the compiler to look up a name inside a specific enclosing scope rather than searching the surrounding scopes. The compiler doesn't guess.

When the code says pricing::withTax(49.99), the compiler does this:

If step 1 fails, the error is "unknown namespace" or "is not a class or namespace". If step 2 fails, the error is "no member named X in namespace Y". The errors are usually quite clear, because the compiler knows a specific scope was requested.

The commented line shows what the error looks like when a name isn't in the scope. The diagnostic names the missing identifier and the namespace it was looked up in.

The diagram shows the two-step lookup that :: triggers. The compiler resolves the left-hand scope first, then searches that scope for the right-hand name. Failure on either side gives a different error. This two-step model is worth keeping in mind, because compiler errors involving :: always mean one of those two steps couldn't be completed.

:: is purely a compile-time operation. It tells the compiler where to look. It generates no runtime cost. catalog::productCount compiles to the same machine code as productCount would if productCount were a global. The namespace exists only in the source and in the linker's mangled symbol names, not in any extra runtime structure.

The C++ standard library puts every name it ships under the std namespace. cout, cin, endl, string, vector, map, sort, swap, move, every container, every algorithm, every IO object: all std::something. This is the namespace encountered first and most often.

When the standard library was added to C++ in the late 1990s, it was clear that dropping vector, list, map, and string directly into the global namespace would break every existing codebase that already used those names. The fix was to put everything under std from day one. Programs written before namespaces (which used <iostream.h> and a global cout) had to be updated, but after that, the library could grow indefinitely without claiming any new global names.

The mechanical impact is that almost every use of a standard library name needs the std:: prefix:

Five identifiers from the standard library appear in that program: string, vector, cout, endl, and (indirectly) size_t through size(). Every one of them is prefixed with std::. The header files (<iostream>, <string>, <vector>) drop their declarations into the std namespace, not into the global scope, which is why the prefix is necessary.

The standard library also declares some nested namespaces under std, like std::chrono for time utilities and std::filesystem for path handling. Those work exactly like any other namespace, just with a longer path:

std::chrono::seconds reads as "the seconds type inside the chrono namespace inside the std namespace". The nested namespace gives chrono its own world inside std, so std::chrono::duration and any future std::duration (if one were ever added) wouldn't collide.

Some code drops the std:: prefix everywhere by writing using namespace std; at the top. Most experienced C++ programmers avoid it in production code, for reasons covered later.

std:: adds five characters to every standard library name, which feels noisy at first. It costs nothing at runtime. The cost is in keystrokes, and the benefit is clarity about which names come from the standard library and which come from project code.

A fully-qualified name starts at the global scope and spells out every enclosing namespace. The global scope is reached by writing :: with nothing before it. So ::std::cout is cout in std in the global scope, while std::cout is cout in std, looked up using the normal rules.

In most code, std::cout and ::std::cout mean the same thing, because the normal lookup finds the same std either way. The difference only matters inside a nested scope that has its own std (unusual but legal), where the leading :: makes the lookup unambiguous.

The leading :: on ::std::cout says "start at the root, then go into std, then find cout". Without it, the compiler first looks for std inside inner, then inside shop, then inside the global scope, and stops at the first hit. In practice the first hit is almost always the global std, so the leading :: is rarely needed. It exists for the cases where it matters, and those cases tend to live in template code or generic libraries that can't predict the scopes they'll be instantiated from.

Fully-qualified names also help when a function name is ambiguous. If both shop::tax and accounting::tax exist, writing the fully-qualified accounting::tax(...) removes any doubt about which one is intended. The compiler won't have to guess based on argument types or surrounding using directives.

A namespace is not a single block declared once. It's a scope that can be reopened any number of times, in the same file or across different files. Every namespace shop { ... } block adds whatever's inside to the same shop namespace.

All three shop blocks contribute to the same namespace. addProduct and getCount can see productCount even though they're declared in separate blocks, because they all share the shop scope. The compiler stitches the pieces together: from the lookup point of view, it's exactly as if everything had been written inside one big block.

This is what makes namespaces work across files. A header file can open shop to declare functions, a source file can open shop to define them, and a different source file can open shop to add even more functions, all without touching the same file twice. The standard library itself is built this way. <iostream>, <vector>, and <string> each reopen std and contribute their own pieces.

The mechanism extends to large projects too. A single namespace like boost is spread across hundreds of header files. None of those files knows about all the others. Each opens boost and adds what it needs.

The diagram shows three header files, each reopening the shop namespace to add one class. The compiler, after preprocessing, sees one logical shop scope that contains Cart, Product, and Order. The split into multiple files is a source-code convenience for humans. The namespace itself behaves as if it had been declared in one place.

One subtle rule: reopening only works for namespaces, not for classes or structs. A namespace can be split across blocks freely, but a class must be defined in one piece. For a "namespace-like" grouping that can grow over time and across files, namespaces are the right tool. Classes are not.

A real codebase splits each module into a header file (the declarations) and a source file (the definitions). Namespaces follow the same split. The namespace is declared in the header, with function signatures and class declarations inside it. The functions and methods are defined in the source file, again wrapped in the same namespace.

A small example showing the pattern. The header declares the namespace and what's in it:

The source file reopens the namespace and provides the bodies:

And the consumer of the module just includes the header and uses the fully-qualified names:

A few details worth pulling out.

The header declares taxRate with extern const. Without extern, a const variable at namespace scope has internal linkage, and including the header in two source files would give each one its own private copy. Adding extern makes the declaration refer to a single shared definition, which lives in the source file.

The source file wraps its definitions inside namespace pricing { ... }. The alternative is to write each definition with the qualified name (double pricing::withTax(double price) { ... }). Both work. The wrapper form is more common with several definitions, because it saves typing the prefix on every one.

The consumer only needs pricing::withTax. It doesn't need a using declaration or any other ceremony. The header pulls the namespace into view, and the scope resolution operator reaches into it.

The diagram shows the three-file flow. pricing.h declares the namespace and its contents. pricing.cpp includes the header and provides the definitions, again inside the pricing namespace. main.cpp includes the header to see the declarations and uses pricing::withTax to call across translation units. The linker matches up the use in main.cpp with the definition in pricing.cpp because the mangled symbol name includes the namespace, so the names are unambiguous even at the linker level.

A common mistake is forgetting to re-wrap the definitions in the namespace in the source file:

What's wrong with this code?

This defines a global withTax, not pricing::withTax. The header declared pricing::withTax, which has no definition anywhere, so the linker reports an "undefined reference to pricing::withTax" error when main.cpp tries to call it. The global withTax is unrelated and never gets called.

Fix: wrap the definitions, or use the qualified form:

Either spelling defines the right function. The linker is strict about namespace membership, which is the point: it's how the language keeps two withTax functions from clashing.

Names declared at file scope, outside any namespace block, live in the global namespace. The global namespace has no name of its own. Reach a name in it by writing ::name, the same syntax as scope::name but with the scope left empty. The empty left-hand side means "the global scope, from the top".

Inside shop::show, the bare productCount resolves to shop::productCount because the surrounding namespace is searched first. To reach the global one, write ::productCount. The leading :: is a precise way of saying "the one in the top-level scope, not whatever this name might mean here".

This syntax is most useful when a local name shadows a global one and the global is still needed. It's also occasionally helpful in template code or macros where the surrounding scope isn't fully known, since ::name is always unambiguous. In day-to-day application code, it appears sparingly, because most code avoids the global scope for anything beyond main and a small handful of constants.

The global namespace is also where everything that isn't inside a namespace ends up by default. The function main always lives in the global namespace; the language specifies this. Plain C library functions like printf and malloc (when accessed through the <cstdio> and <cstdlib> headers) are also injected into std, but their <stdio.h> and <stdlib.h> counterparts inject them into the global namespace as well, for compatibility with C code.

A slightly larger example that uses everything covered so far: a small e-commerce program with two namespaces, a customers namespace and an orders namespace, each opened across two blocks, with the consumer in main reaching into both using qualified names.

customers and orders are both opened twice. The first opening declares the types and the shared state. The second opening defines the helper functions. The compiler merges each pair, so registerCustomer can see registeredCount and placeOrder can see placed, even though those names were introduced in earlier blocks.

In main, every reference into either namespace is fully qualified: customers::Customer, customers::registerCustomer, orders::Order, orders::placeOrder, orders::placed. The code is verbose, but the verbosity is informative: every name carries its origin. If a third namespace also defined a placeOrder, the existing code would still compile and behave the same way, because the namespace prefix removes any ambiguity. That property is the reason namespaces exist.