cppdotenv

A header-only C++17 library for reading .env files. Inspired by python-dotenv.

• Header-only, single include: #include <cppdotenv/dotenv.hpp>
• No runtime dependencies
• C++17, CMake INTERFACE target
• Supports ${VAR} / $VAR expansion, ${VAR:-default}, quoted values, multi-line values, export prefix, and inline comments

Install

CMake FetchContent

include(FetchContent)
FetchContent_Declare(
    cppdotenv
    GIT_REPOSITORY https://github.com/fox1245/cppdotenv.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(cppdotenv)

target_link_libraries(your_target PRIVATE cppdotenv::cppdotenv)

Copy the header

Drop include/cppdotenv/dotenv.hpp into your project and add include/ to your include path.

System install

cmake -S . -B build -DCPPDOTENV_BUILD_TESTS=OFF
cmake --install build --prefix /usr/local

Then in your consumer CMakeLists.txt:

find_package(cppdotenv CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE cppdotenv::cppdotenv)

Quick start

Given a .env file:

# database
DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
APP_NAME=cppdotenv
LOG_PREFIX="[${APP_NAME}]"

Load it into the process environment:

#include <cppdotenv/dotenv.hpp>
#include <cstdlib>
#include <iostream>

int main() {
    cppdotenv::load_dotenv(".env");
    std::cout << std::getenv("DATABASE_URL") << "\n";
}

Or read it into a map without touching getenv:

auto values = cppdotenv::dotenv_values(".env");
std::cout << values["LOG_PREFIX"] << "\n";  // [cppdotenv]

API

All functions live in namespace cppdotenv.

Function	Purpose
Dict dotenv_values(path, interpolate=true)	Parse a .env file into a std::map<string,string>.
Dict dotenv_values_from_string(content, interpolate=true, use_process_env=true)	Parse a string as .env content.
Dict parse_stream(istream&, interpolate=true, use_process_env=true)	Parse an arbitrary input stream.
bool load_dotenv(path, override_existing=false, interpolate=true)	Load a .env file into the process environment.
path auto_load_dotenv(filename=".env", override_existing=false, interpolate=true)	Walk up from cwd, find the file, and load it. Returns the path actually loaded (empty if none).
path find_dotenv(filename=".env", start=cwd)	Walk up directories to locate a file.
optional<string> get_key(path, key, interpolate=true)	Read a single key's value.
bool set_key(path, key, value, quote='"')	Insert or update a key. Preserves the existing key's quote style when updating.
bool unset_key(path, key)	Remove a key.

Dict is std::map<std::string, std::string>.

Parsing rules

• Lines starting with # and blank lines are ignored.
• export FOO=bar is accepted; the export prefix is stripped.
• Values can be unquoted, single-quoted, or double-quoted.
• Double-quoted values support \n, \r, \t, \\, \", \' escapes and variable expansion.
• Single-quoted values are literal — no escapes, no expansion.
• Unquoted values have trailing # comment stripped and surrounding whitespace trimmed.
• Multi-line values are supported inside double or single quotes.
• Variable expansion:
  • $NAME and ${NAME} are substituted.
  • ${NAME:-default} / ${NAME-default} supply a default when unset (or empty, for :-).
  • \$ is a literal $.
  • Later keys in the same file can reference earlier ones.
  • When use_process_env=true, undefined names fall back to the process environment.

Build and test

cmake -S . -B build
cmake --build build -j
ctest --test-dir build --output-on-failure

Options:

• -DCPPDOTENV_BUILD_TESTS=ON/OFF (default ON)
• -DCPPDOTENV_BUILD_EXAMPLES=ON/OFF (default ON)

License

MIT. See LICENSE.