C++
Language
Basic

Namespace Alias

Introduce an alternate name for a namespace to shorten deeply-nested paths or pin versioned namespaces to a stable local identifier.

Namespace Aliassince C++98

A namespace alias binds a new identifier to an existing namespace (or chain of nested namespaces), providing an alternate, scope-limited name through which the namespace's members can be accessed.

Overview

Namespace aliases solve a narrow but recurring problem: long or deeply-nested namespace paths create noise that obscures intent. Rather than typing boost::filesystem or std::chrono::literals at every use site, you can introduce a local alias and use the shorter name without changing what the code actually refers to.

The alias is not a new namespace — it is a second name for an existing one. Any declaration made through the alias appears in the original namespace, and any declaration added to the original namespace afterward is immediately visible through the alias. This transparency distinguishes namespace aliases from, say, type aliases, where the two names may differ in ways that affect overload resolution or template specialization.

Namespace aliases were part of the original C++98 standard and have remained unchanged through C++26, except for a reflection-based splice-specifier form added in C++26 that is not yet widely implemented.

Syntax

cpp
namespace alias_name = ns_name;            // (1) unqualified
namespace alias_name = ::ns_name;          // (2) from global scope
namespace alias_name = nested::ns_name;    // (3) through another namespace

alias_name must not already name something in the current scope. The alias is valid for the duration of its enclosing scope — it may appear at namespace scope, block scope, or inside a function. All three forms follow the same rules; the difference is only in how ns_name is looked up.

The alias can itself be used on the right-hand side of another alias:

cpp
namespace fs  = std::filesystem;       // C++17
namespace fsd = fs::directory_options; // error: directory_options is a type, not a namespace
namespace fsp = fs::path;              // error: path is a type, not a namespace

Only namespaces (not types, variables, or functions) can appear on the right-hand side.

Examples

Shortening std::filesystem

Without an alias, filesystem code grows unwieldy:

cpp
#include <filesystem>
#include <iostream>

// Without alias — verbose at every use site
void list_dir_verbose(const std::filesystem::path& p) {      // C++17
    for (const std::filesystem::directory_entry& e :         // C++17
             std::filesystem::directory_iterator(p)) {       // C++17
        std::cout << e.path().filename() << '\n';
    }
}

// With alias — identical semantics, far less noise
namespace fs = std::filesystem;                              // C++17

void list_dir(const fs::path& p) {
    for (const fs::directory_entry& e : fs::directory_iterator(p))
        std::cout << e.path().filename() << '\n';
}

Version-pinning in library code

A common pattern in library headers that must remain compatible across multiple implementations:

cpp
// In a library implementation file (.cpp), NOT the header
namespace impl = mylib::v2::detail;   // switch the whole implementation in one line

void MyClass::process() {
    impl::run(data_);
    impl::flush();
}

Changing a single alias declaration swaps which version of detail the entire translation unit uses. This is far safer than a global find-and-replace.

Namespace alias in block scope

Aliases are not limited to namespace scope — they work inside functions too:

cpp
#include <chrono>

void animate(double seconds) {
    namespace ch = std::chrono;                              // C++11

    auto duration = ch::duration_cast<ch::milliseconds>(
        ch::duration<double>(seconds));

    // ch is only visible within this function body
}

Block-scope aliases are useful when you want to avoid cluttering a header while still keeping a function's body readable.

Deeply-nested third-party namespaces

cpp
// Long canonical name from a typical C++ library
// vendor::core::platform::v3::detail::io
namespace io = vendor::core::platform::v3::detail::io;

io::Stream open(const char* path) {
    io::Options opts;
    opts.flags = io::Flags::NonBlocking;
    return io::open_stream(path, opts);
}

Best Practices

Keep aliases out of headers. Defining a namespace alias at the top level of a header file forces it on every translation unit that includes that header. This is the same problem as using namespace foo; in a header, only slightly less severe. Restrict aliases to .cpp files, or at worst to anonymous namespaces or inline function bodies in headers.

cpp
// bad — alias leaks into all includers
// mylib.h
namespace ml = mylib::internal;   // pollutes every TU

// good — alias is local to this file
// mylib.cpp
namespace ml = mylib::internal;

Use aliases to pin implementation namespaces. When you have versioned namespaces (v1, v2) or platform-specific sub-namespaces (posix, win32), a single alias at the top of a .cpp makes switching the implementation a one-line change with zero risk of partial updates.

Prefer aliases over repeated qualified names in long functions. A threshold of three or more uses of the same long namespace path in one function or scope is a reasonable trigger for introducing a local alias. Below that, the overhead of a new name may not pay off.

Alias, don't typedef namespaces. There is no way to typedef a namespace — the alias syntax shown here is the only mechanism. Do not reach for using declarations (which pull individual names into scope) when what you actually want is the whole namespace accessible under a shorter path.

Common Pitfalls

An alias is not a new namespace. You cannot add new declarations to a namespace through its alias:

cpp
namespace fbz = foo::bar::baz;

namespace fbz {        // error: fbz is an alias, not a namespace definition
    int extra = 1;     // this would need to go inside foo::bar::baz directly
}

If you need to extend the namespace, refer to it by its canonical name.

The alias name must be unused in its scope. Attempting to reuse a name that already exists — including a prior alias — is ill-formed:

cpp
namespace A { int x; }
namespace B { int y; }

namespace AB = A;
namespace AB = B;   // error: AB already refers to A

This is rarely a problem in practice, but it can surface when auto-generating code or when multiple headers define the same alias for different namespaces.

Aliases in templates do not deduce like types do. A namespace alias in a template context is still just a namespace; the alias name does not participate in template argument deduction or ADL in any special way. The alias is purely a naming convenience resolved at parse time.

Aliasing the wrong level of nesting. When a namespace hierarchy is deep, aliasing one level too high or too low gives an identifier that still requires qualification at the use site or one that over-shortens to something ambiguous:

cpp
namespace fs  = std::filesystem;           // correct for most use
namespace fse = std::filesystem::__detail; // never alias internal/detail namespaces;
                                           // they are not part of the public API

See Also