# Asio vs Boost.Asio: Key Differences Explained

> Understand the key differences between Asio and Boost.Asio. Explore namespace, distribution, and dependency distinctions in this header-only C++ library.

- Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio)
- Tags: deep-dive
- Published: 2026-07-16

---

**Asio is a stand-alone, header-only C++ library that provides the same asynchronous I/O functionality as Boost.Asio, differing primarily in namespace (`asio::` vs `boost::asio::`), distribution model, and dependency requirements.**

The `chriskohlhoff/asio` repository hosts the stand-alone version of Asio, a cross-platform library for network and low-level I/O programming. Understanding the difference between Asio and Boost.Asio helps you choose the right variant for your project’s build requirements and dependency constraints.

## Namespace and Distribution Model

The most visible distinction between the two variants is the **namespace** used throughout the API.

- **Stand-alone Asio**: Uses the `asio::` namespace (e.g., `asio::io_context`, `asio::ip::tcp`)
- **Boost.Asio**: Uses the `boost::asio::` namespace (e.g., `boost::asio::io_context`)

**Distribution** differs significantly:

- **Asio** distributes as a single repository with no required Boost dependencies. You include [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) and link against your build system without pulling the entire Boost distribution.
- **Boost.Asio** lives within the Boost library collection. It requires a Boost tree and may pull in other Boost components automatically via Boost’s autolink mechanism.

## Build Configuration and Dependencies

Both variants are **header-only by default**, but support optional separate compilation to reduce build times.

Configuration macros differ by prefix:

- Stand-alone macros are defined in [`asio/config.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/config.hpp) (e.g., `ASIO_SEPARATE_COMPILATION`, `ASIO_DYN_LINK`, `ASIO_NO_DEPRECATED`)
- Boost.Asio uses the same macros but prefixed with `BOOST_ASIO_` (e.g., `BOOST_ASIO_SEPARATE_COMPILATION`)

To enable separate compilation in stand-alone Asio, include [`asio/impl/src.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/impl/src.hpp) and define `ASIO_SEPARATE_COMPILATION`. According to the documentation in `src/doc/using.qbk`, stand-alone Asio does not require optional Boost libraries (such as Coroutines, Regex, or Date_Time) for core I/O functionality—these are only needed for specific extensions.

## API Compatibility and Code Examples

**The API surface is identical** between the two variants. Code written for `boost::asio` compiles unchanged when you replace the `boost::` namespace with `asio::`.

The following TCP echo server demonstrates the minimal changes required:

**Stand-alone Asio (`asio::`):**

```cpp
#include <asio.hpp>

using asio::ip::tcp;

int main() {
  asio::io_context io;
  tcp::acceptor acceptor(io, tcp::endpoint(tcp::v4(), 12345));

  std::function<void()> do_accept;
  do_accept = [&]() {
    acceptor.async_accept([&](std::error_code ec, tcp::socket sock) {
      if (!ec) {
        std::shared_ptr<tcp::socket> s = std::make_shared<tcp::socket>(std::move(sock));
        asio::async_read_until(*s, asio::dynamic_buffer(*s), '\n',
            [s](std::error_code ec, std::size_t) {
              if (!ec) asio::async_write(*s, asio::buffer("echo\n"),
                  [s](std::error_code, std::size_t) {});
            });
      }
      do_accept();
    });
  };
  do_accept();
  io.run();
}

```

**Boost.Asio (`boost::asio::`):**

```cpp
#include <boost/asio.hpp>

using boost::asio::ip::tcp;

/* ... the rest of the program is identical, only the namespace changes ... */

```

Key implementation files in the repository include:
- [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) – Primary public header
- [`include/asio/io_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/io_context.hpp) – Core I/O execution context
- [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp) – TCP socket types and acceptor
- `boost_asio.manifest` – Describes how Asio integrates into Boost’s source tree

## Versioning and Binary Compatibility

**Release cycles** differ between the two distributions:

- **Asio** follows an independent release cycle (e.g., version 1.38.1 released May 2026)
- **Boost.Asio** versions are tied to Boost releases (e.g., Boost 1.86 ships Boost.Asio v1.28)

**Binary compatibility** also varies:

- Stand-alone Asio has no reliance on Boost’s ABI, allowing you to link against any project that includes the headers
- Boost.Asio follows Boost’s ABI rules, requiring matching Boost versions when linking against Boost-built libraries

Both libraries use the **Boost Software License 1.0**.

## Summary

- **Namespace**: Stand-alone uses `asio::`; Boost uses `boost::asio::`
- **Dependencies**: Stand-alone requires no Boost libraries for core functionality; Boost.Asio requires the Boost distribution
- **Configuration**: Macros use `ASIO_` prefix in stand-alone, `BOOST_ASIO_` in Boost
- **API**: Identical functionality; code ports by changing namespaces
- **Distribution**: Single repository vs. integrated Boost library
- **Versioning**: Independent releases vs. tied to Boost release schedule

## Frequently Asked Questions

### Can I use Asio without installing Boost?

Yes. Stand-alone Asio in the `chriskohlhoff/asio` repository requires no Boost libraries for core asynchronous I/O operations. You only need optional Boost components if you use specific extensions like Boost.Coroutine integration, as documented in `src/doc/using.qbk`.

### Is the API identical between Asio and Boost.Asio?

Yes, the API surface is identical. Most code written for `boost::asio` compiles unchanged when you replace `boost::asio` with `asio`. The implementation files (such as [`include/asio/io_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/io_context.hpp) and [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp)) provide the same classes and methods as their Boost counterparts.

### How do I switch from Boost.Asio to stand-alone Asio?

Change your includes from `<boost/asio.hpp>` to `<asio.hpp>`, replace the `boost::asio` namespace with `asio`, and update configuration macros from `BOOST_ASIO_*` to `ASIO_*`. No changes to your application logic are required since the underlying implementation is the same code base.

### Which should I choose for a new project?

Choose **stand-alone Asio** if you want a lightweight async I/O library without the full Boost distribution footprint. Choose **Boost.Asio** if your project already depends on Boost libraries or if you prefer the unified Boost ecosystem and its build system integration.