# How to Include Asio in a C++ Project: Header-Only Setup Guide

> Easily integrate Asio into your C++ project using its header-only setup. Learn how to add Asio to your compiler's include path and start building powerful network applications today.

- Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio)
- Tags: how-to-guide
- Published: 2026-07-16

---

**You can include Asio in your C++ project by adding the repository's `include/` directory to your compiler's search path and including `<asio.hpp>` in your source files, as the library is entirely header-only.**

The **Asio** library from the `chriskohlhoff/asio` repository provides cross-platform, low-level I/O services including sockets, timers, and asynchronous operations for modern C++ applications. Because it is header-only, you do not need to compile separate libraries or link binaries—just configure your include paths correctly. This guide shows you exactly how to include Asio in a C++ project using standard build tools and compiler flags.

## Obtaining the Asio Source Code

First, download the source code to your local machine. You can clone the repository directly or download a release archive from the GitHub releases page.

```bash
git clone https://github.com/chriskohlhoff/asio.git

```

The critical directory is `include/` at the root of the repository, which contains all the header files you need. The primary umbrella header is located at [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp), though you can also include more granular headers like [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp) or [`include/asio/steady_timer.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/steady_timer.hpp) to reduce compilation times.

## Configuring the Include Path

Since Asio is header-only, you must tell your compiler where to find the headers. This typically involves adding the path to the `include/` directory as an additional include directory.

### GCC and Clang

When compiling with GCC or Clang, use the `-I` flag to specify the path to the Asio `include/` directory.

```bash
g++ -std=c++11 -I/path/to/asio/include main.cpp -o my_app

```

Replace `/path/to/asio` with the actual location where you cloned or extracted the repository.

### Visual Studio

In Visual Studio, right-click your project and navigate to **Configuration Properties** → **C/C++** → **General**. Add the path to the Asio `include/` directory to **Additional Include Directories**. You can then compile with the default MSVC toolchain without additional linker flags for the core library.

## Including the Headers in Your Source Files

Once the include path is configured, add the headers to your C++ source files. The simplest approach is to include the umbrella header [`asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio.hpp), which pulls in the entire API.

```cpp
#include <asio.hpp>

```

For better compile times, include only the specific components you need. For example, use [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp) for TCP networking, [`include/asio/steady_timer.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/steady_timer.hpp) for timers, or [`include/asio/co_spawn.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/co_spawn.hpp) for C++20 coroutine support.

## Linking Requirements

Asio's core functionality requires **no linking** against a compiled library. However, certain optional features require third-party libraries:

- **SSL Support**: If you use [`include/asio/ssl.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ssl.hpp), you must link against OpenSSL using `-lssl` and `-lcrypto` (GCC/Clang) or by adding the appropriate libraries in Visual Studio.
- **Boost Integration**: If you use the Boost.Asio compatibility mode or Boost-specific executor types, link against the corresponding Boost libraries.

## Complete Working Examples

Here are practical examples demonstrating how to use Asio after including it in your project.

### Synchronous TCP Client

This example uses [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) and [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp) to resolve a hostname and send an HTTP request.

```cpp
#include <asio.hpp>
#include <iostream>

int main() {
    try {
        asio::io_context ctx;
        asio::ip::tcp::resolver resolver(ctx);
        auto endpoints = resolver.resolve("example.com", "80");

        asio::ip::tcp::socket socket(ctx);
        asio::connect(socket, endpoints);

        const std::string request =
            "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n";
        asio::write(socket, asio::buffer(request));

        for (char buf[512];;) {
            std::size_t n = socket.read_some(asio::buffer(buf));
            std::cout.write(buf, n);
        }
    } catch (std::exception& e) {
        std::cerr << "Error: " << e.what() << "\n";
    }
}

```

### Asynchronous Timer with Coroutines

This example uses [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp), [`include/asio/co_spawn.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/co_spawn.hpp), and [`include/asio/awaitable.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/awaitable.hpp) for C++20 coroutines.

```cpp
#include <asio.hpp>
#include <iostream>

asio::awaitable<void> timer_task() {
    asio::steady_timer t(co_await asio::this_coro::executor);
    t.expires_after(std::chrono::seconds(2));
    co_await t.async_wait(asio::use_awaitable);
    std::cout << "Timer fired after 2 seconds\n";
}

int main() {
    asio::io_context ctx;
    asio::co_spawn(ctx, timer_task(), asio::detached);
    ctx.run();
}

```

### SSL Client Setup

This example requires [`include/asio/ssl.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ssl.hpp) and linking against OpenSSL.

```cpp
#include <asio.hpp>
#include <asio/ssl.hpp>
#include <iostream>

int main() {
    asio::io_context ctx;
    asio::ssl::context ssl_ctx(asio::ssl::context::tlsv12_client);
    ssl_ctx.set_default_verify_paths();

    asio::ssl::stream<asio::ip::tcp::socket> stream(ctx, ssl_ctx);
    asio::ip::tcp::resolver resolver(ctx);
    auto endpoints = resolver.resolve("www.google.com", "https");
    asio::connect(stream.lowest_layer(), endpoints);
    stream.handshake(asio::ssl::stream_base::client);

    std::cout << "SSL handshake completed\n";
}

```

## Summary

- **Asio is header-only**: Add the `include/` directory from `chriskohlhoff/asio` to your compiler's search path.
- **Primary header**: Use [`include/asio.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) for the full API, or granular headers like [`include/asio/ip/tcp.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ip/tcp.hpp) for specific components.
- **No core linking required**: The library does not require linking against a binary, though OpenSSL is required for [`include/asio/ssl.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ssl.hpp).
- **Standards support**: Requires C++11 or later, with enhanced features available in C++17 and C++20.

## Frequently Asked Questions

### Is Asio header-only?

Yes, Asio is entirely header-only. You do not need to compile the source files or link against a `.lib` or `.a` file for core functionality. Simply add the `include/` directory to your compiler's include path and start using the headers.

### Do I need to link a library to use Asio?

Core Asio functionality requires no linking. However, if you use SSL features via [`include/asio/ssl.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/ssl.hpp), you must link against OpenSSL. Additionally, if you use Boost.Asio integration or Boost-specific components, you must link against the relevant Boost libraries.

### What is the difference between standalone Asio and Boost.Asio?

Standalone Asio resides in the `chriskohlhoff/asio` repository and places all classes in the `asio::` namespace. Boost.Asio is the same codebase distributed with Boost, using the `boost::asio::` namespace. Both share identical header layouts and APIs, so the inclusion method is the same—only the namespace and distribution mechanism differ.

### Which C++ standard version does Asio require?

Asio requires **C++11** or later. Many modern features, such as the `awaitable` coroutine support in [`include/asio/awaitable.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/awaitable.hpp), require **C++20**. The library works with any conforming compiler including GCC, Clang, and MSVC.