C++ namespace: declare, nest, alias and reopen

A namespace in C++ is a named scope: a region of the program whose names do not collide with the same names elsewhere. namespace shop { int total = 0; } puts total inside shop, and code outside reaches it as shop::total. The standard library lives in a namespace called std, which is why you write std::cout.

A shop’s running total, as a whole program:

#include <iostream>

namespace shop {
int total = 0;

void add(int price) { total += price; }
}

int main() {
    shop::add(5);
    shop::add(3);
    std::cout << "total: " << shop::total << '\n';  // total: 8
}

It printed total: 8. Inside shop, add uses total with no prefix; outside, main writes shop:: in front of both.

The samples are C++17, built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++), and all four behaved the same. Since When lists the first compiler releases for each standard’s features.

Why use namespaces in C++?

So that one name can mean two things in one program. An audio library and a video library may each have a function called play; in two namespaces both fit, and the name before :: says which one you call:

namespace audio {
void play() { std::cout << "audio: playing the track\n"; }
}

namespace video {
void play() { std::cout << "video: playing the clip\n"; }
}

int main() {
    audio::play();
    video::play();
}

It printed audio: playing the track, then video: playing the clip.

With no namespaces, the second play is a second definition of the same function:

void play() { std::cout << "audio: playing the track\n"; }
void play() { std::cout << "video: playing the clip\n"; }  // error

GCC stopped at the second line with redefinition of 'void play()', and the other three rejected it too.

Can a namespace be reopened or split across files?

Yes. Every namespace shop { ... } block at the same level adds to the same namespace, and the blocks may sit in one file or in several ([basic.namespace]). That is how a header file and its source file share a namespace: the header declares the functions inside shop, and the source file defines them, either in another shop block or outside any block with the full name. This sample does both in one file:

namespace shop {
int total = 0;
int total_price();  // declared here, defined further down
}

namespace shop {  // reopened: adds to the same namespace
void add(int price) { total += price; }
}

int shop::total_price() {  // defined outside, with the full name
    return total;  // inside, total means shop::total
}

With a main that adds 5 and 3 and prints shop::total_price(), it printed total price: 8.

Using declaration vs using directive

A using declaration, using shop::total;, brings one name into the scope where you write it, so total alone means shop::total there. A using directive, using namespace shop;, makes every name in shop usable without the prefix. It adds no names to the scope it sits in; it changes where a name written without a prefix is looked up. With the shop of the first program:

void add_one() {
    using namespace shop;  // every name in shop, in this function
    add(1);                // shop::add
}

int main() {
    using shop::total;  // one name: total
    shop::add(5);
    add_one();
    std::cout << "total: " << total << '\n';  // shop::total
}

It printed total: 6: 5 added in main, 1 in add_one.

A directive also lets you reach names you did not ask for, and two directives that offer the same function with the same parameters make a call with no prefix ambiguous:

int main() {
    using namespace audio;
    using namespace video;
    play();  // error: audio::play or video::play?
}

GCC said call of overloaded 'play()' is ambiguous, and the other three rejected it too. using namespace std; is the same directive for the standard library: what using namespace std does, and what to write instead has its clashes, and argument-dependent lookup, the rule that lets a call find a function through its argument’s namespace.

How do you write a nested namespace?

Put one namespace inside another and reach its names through both, as app::net::send(). Since C++17 a single line opens both at once, namespace app::net { }, and means the same as the two nested blocks:

namespace app {
namespace net {
void send() { std::cout << "net: sent\n"; }
}
}

namespace app::net {  // C++17: opens both at once
void receive() { std::cout << "net: received\n"; }
}

Called as app::net::send() and app::net::receive(), it printed net: sent, then net: received. Built as C++14, MSVC refused the short form and asked for /std:c++17; Clang warned, and GCC warned only with -pedantic. Since When’s C++17 table has the first compiler releases that support it.

What is a namespace alias?

A namespace alias is a second, shorter name for a namespace: after namespace net = app::net;, net::send() calls app::net::send() (namespace aliases on cppreference). The alias you will meet most is fs, for std::filesystem (C++17, from <filesystem>):

namespace net = app::net;  // a shorter name for app::net
namespace fs = std::filesystem;

int main() {
    net::send();
    std::cout << fs::path{"shop/cart.txt"}.filename().string() << '\n';
}

It printed net: sent, then cart.txt. An alias cannot be reopened: after it, namespace net { } failed on all four compilers, so add to the namespace under its real name, namespace app::net { }.

What is an unnamed (anonymous) namespace?

An unnamed namespace, also called an anonymous namespace, is namespace { } with no name. What is inside can be used in this translation unit (the source file and the headers it includes) and nowhere else, because everything declared in it has internal linkage (Namespaces on cppreference). It is the C++ way to keep a helper function private to one file, where C code marks it static:

namespace {  // no name: usable in this file only
int with_tax(int price) { return price + price / 5; }
}

int main() {
    std::cout << "with tax: " << with_tax(10) << '\n';
}

It printed with tax: 12. with_tax needs no prefix because the block behaves as a namespace with a unique name followed by a using directive for it ([namespace.unnamed]).

The namespace forms at a glance

The Language section has the other answers on the core language.