Namespaces

What it is and why it exists

A C++ program uses the standard library, third-party libraries, and project code together. Each may reasonably need names such as parse, Status, or Config. Namespaces place those declarations in different scopes so wire::Status and storage::Status can coexist.

A namespace is a declarative region, not an object, and you can’t instantiate it. It has no public, private, or protected access control; code that knows a name can use an otherwise accessible declaration. project::detail states a convention but doesn’t force outside code to stay away.

A namespace isn’t a directory or a build target either. You can extend one namespace across several headers and source files, and one file can contain several namespaces. Projects often keep directory and namespace hierarchies similar for readers, but the language doesn’t require that layout.

You encounter namespaces in nearly every C++ interface. Standard library names are in std; libraries commonly use an organization or library name as the outer namespace and add domain-oriented nesting in larger codebases. C++17 added the compact nested definition syntax namespace company::billing { ... }.

Namespaces solve name ownership and lookup. Header inclusion, the one-definition rule, and whether the linker can find a symbol belong to the compilation and linking model. Keeping those concerns separate is necessary when, for example, code compiles but fails to link.

How it works

A namespace definition adds declarations to a namespace scope. Writing another definition with the same name later reopens the original namespace; it doesn’t create a second container with the same name. A header can therefore declare shop::load(), and a source file can provide its definition inside namespace shop { ... }.

A namespace definition can only appear at namespace scope, not inside a function or class. Inside a function, you may declare a namespace alias or use a using declaration or directive. This distinction catches generated code that tries to create a namespace inside a function for “local isolation”: that code doesn’t compile.

Qualified and unqualified lookup

billing::total is a qualified name, so lookup continues in the scope denoted by billing. A leading :: makes a fully qualified name start at the global namespace. For example, ::company::billing::total doesn’t first try a company declared in the current nested scope.

The unqualified name total uses unqualified name lookup. The compiler searches the current scope and then the outer scopes prescribed by the language. Finding candidate names doesn’t finish a function call; function candidates must still go through overload resolution.

For an unqualified function call, the compiler may also perform argument-dependent lookup (ADL) . Namespaces and classes associated with the argument types contribute more candidates, so print(parcel) can find shipping::print placed alongside shipping::Parcel. The qualified call shipping::print(parcel) doesn’t need ADL.

ADL only supplements particular forms of function lookup; it doesn’t “guess any name from the arguments.” It is also suppressed when ordinary unqualified lookup finds a class member, a block-scope function, or a non-function declaration. When debugging an overload, list ordinary-lookup candidates separately from those supplied by ADL.

using declarations, directives, and aliases

A using declaration introduces a named declaration, as in using metrics::distance;. The current scope can then write distance(...), while the decision remains visible on one line. A function overload set can be introduced under one name, but that doesn’t import the whole namespace.

A using directive has the form using namespace metrics;. It makes unqualified lookup consider names from that namespace; it doesn’t declare a local copy of every member. A later addition to the namespace can turn a formerly unambiguous call into an ambiguous one.

A namespace alias gives a shorter spelling to a long name, as in namespace api = company::platform::api;. It doesn’t copy members or create a new namespace; the alias and original name reach the same declarations. Aliases are useful local conveniences in a .cpp file or function, but public interfaces shouldn’t depend on abbreviations chosen by callers.

Unnamed and inline namespaces

An unnamed namespace is written namespace { ... }. Names declared directly or indirectly within it have internal linkage and belong to the current translation unit . Several unnamed namespace definitions in one translation unit reopen the same unique namespace.

Unnamed namespaces suit helper functions, constants, and implementation types in a .cpp file. In a header, each translation unit that includes the header gets its own entities. That can be intentional, but it can also duplicate state and create type-identity problems.

Members of an inline namespace can also be found by qualified lookup through the enclosing namespace. Libraries often use one to give the current API version a short name while preserving explicit spellings such as library::v1::Type and library::v2::Type. It doesn’t automatically make the two versions source- or ABI-compatible.

Examples

The next four programs show name isolation, namespace extension, ADL, and unnamed and inline namespaces. Each was compiled and run locally with g++ in -std=c++23 mode; the recorded output is from those runs.

Isolating functions with the same name

Both domains can use the name fee. Each call site selects a rule with a qualified name, and a very small scope gives one namespace an alias.

bulk is only another spelling of wholesale. It has no separate fee and doesn’t change the function’s type or linked symbol. Keeping the calls qualified is clearer here than introducing both functions under the name fee.

Extending a namespace in several places

The first definition adds Order; the second adds make_order(). The C++17 nested syntax then defines shop::audit::write(). All three regions contribute to one connected set of namespace scopes.

#include <iostream>

namespace shop {
struct Order {
    int id;
    int units;
};
}

namespace shop {
Order make_order(int id, int units) {
    return {id, units};
}
}

namespace shop::audit {
void write(const Order& order) {
    std::cout << "order " << order.id
              << ": " << order.units << " units\n";
}
}

int main() {
    const auto order = shop::make_order(42, 3);
    shop::audit::write(order);
}

order 42: 3 units

Inside audit, the enclosing shop namespace’s Order can be unqualified. The caller still writes shop::audit::write, because an ordinary nested namespace doesn’t expose its members through the enclosing namespace as an inline namespace does.

A real project usually puts Order and the function declarations in a header and the function definitions in a source file. The sample uses one file so it can run alone. A namespace can span files, but each translation unit still needs declarations for the names it uses.

Letting ADL find an operation from the same domain

shipping::print lives in the same namespace as the Parcel it handles. main() has no using shipping::print, yet the unqualified call can associate the argument type with shipping.

#include <iostream>
#include <string_view>

namespace shipping {
struct Parcel {
    std::string_view route;
    int weight_kg;
};

void print(const Parcel& parcel) {
    std::cout << parcel.route << ": "
              << parcel.weight_kg << " kg\n";
}
}

int main() {
    const shipping::Parcel parcel{"CDG-BER", 12};
    print(parcel);  // ADL adds shipping::print.
}

CDG-BER: 12 kg

If the argument changed to a built-in type unrelated to shipping, ADL wouldn’t have that associated namespace. Placing an operation alongside its user-defined type is what lets operators and many customization points work naturally.

You could write shipping::print(parcel) here instead. Whether to rely on ADL depends on the interface contract: ordinary business calls can usually be qualified, while generic calls designed for customization often need to remain unqualified.

Selecting a default API version

The outer name telemetry::format finds the inline v2 version, while the old version remains explicitly accessible. An unnamed namespace holds a call counter private to this translation unit.

#include <iostream>
#include <string>

namespace telemetry {
namespace v1 {
std::string format(int value) {
    return "value=" + std::to_string(value);
}
}

inline namespace v2 {
std::string format(int value) {
    return "metric:" + std::to_string(value);
}
}
}

namespace {
int calls = 0;
}

int main() {
    ++calls;
    std::cout << telemetry::format(7) << '\n';
    std::cout << telemetry::v1::format(7) << '\n';
    std::cout << "calls: " << calls << '\n';
}

metric:7
value=7
calls: 1

telemetry::v2::format(7) is also valid. Here inline changes lookup and some association rules; it doesn’t carry the function-optimization meaning of the other use of the same keyword.

calls isn’t a member of telemetry. It provides an internal entity only in this translation unit, which fits an implementation detail. Code that needs one counter across files should declare an explicit external interface in a named namespace.

Pitfalls

Writing using namespace in a header

Fix: use qualified names in headers. If repeated qualification genuinely harms readability inside an implementation function, introduce only the needed name in the smallest practical block scope.

Treating detail as access control

Fix: use private class members for object invariants, an unnamed namespace for .cpp-local names, and module export rules for module interfaces. Don’t treat a namespace name as a security boundary.

Creating one state object per translation unit in a header

Fix: first state whether ownership is per translation unit or program-wide. Put shared state behind one definition in a suitable namespace, or use a C++17 inline variable when its contract permits. Document independent state when that behavior is intentional.

Adding your own declarations to std

Fix: put a type and its non-member operations in your own namespace so ADL can find them. For generic swapping, introduce std::swap and then call swap(a, b) unqualified, or use std::ranges::swap when that matches the target library contract.

Letting a qualified call bypass ADL customization

Fix: confirm whether an API defines ADL as part of its customization protocol. Follow that protocol with an unqualified call and test at least one custom type. Prefer qualification for ordinary calls to an operation owned by a known namespace.

Defining a function in the wrong namespace

Fix: define the function with an explicit qualified name or open exactly the same namespace as its declaration. Compile and link a minimal caller. Running only -fsyntax-only on the source file can’t detect a missing definition.

Further reading

• C++ working draft: namespaces
• C++ working draft: using directives
• C++ working draft: argument-dependent name lookup
• cppreference: namespaces
• cppreference: argument-dependent lookup