Microsoft Detours: instrumenting Windows API calls from source

What problem Detours solves, and who it is actually for

Detours exists for one job: monitoring and instrumenting API calls on Windows. The README describes it as a software package used by independent software vendors and by product teams at Microsoft, which tells you the intended audience is people shipping or maintaining Windows binaries, not casual scripters. If you need to log every call a process makes to a Win32 function, redirect that call to your own implementation, or attach payload code to an existing binary, that is the problem space Detours occupies.

The scope is narrower than the name suggests. Detours operates on Windows NT family systems, and the README lists Windows NT, Windows XP, Windows Server 2003, Windows 7, Windows 8, Windows 10 and Windows 11 as compatible. It is a C++ library distributed in source form, so you are expected to have a Windows build environment and a reason to link against a library rather than use a finished tool. The README explicitly excludes Windows Store apps because Detours requires APIs those applications cannot reach. That single sentence rules out an entire class of modern Windows software and is the first thing to check against your target.

How interception works in the Detours package

The repository layout tells you how the package is organized. There is a src directory holding the library itself, a samples directory with twenty-odd example projects, a tests directory, and a vc directory for Visual Studio build files. The samples are the practical documentation: comeasy, commem, cping, disas, dtest, dumpe, dumpi, dynamic_alloc, echo, einst, excep, findfunc, impmunge, member, opengl, payload, region, setdll, simple, simple_safe, slept and syelog. The source lists only the directory names; what each sample does is in samples/README.TXT and the samples themselves.

What the package does at runtime is not spelled out in the README, which points to the Detours Wiki for technical documentation. That is a real gap for anyone evaluating the library from the repository alone: the README tells you what Detours is for, not how a detour is installed or what happens to the original function. The sample names are the best available signal of the intended mechanisms, and the presence of both a simple and a simple_safe sample suggests the straightforward approach has a variant that trades something for reliability.

Building Detours from source with nmake

Detours is distributed in source code form, so there is no installer to run. The top-level Makefile is an nmake makefile that includes system.mak and then descends into src, samples and tests in turn. The samples README.txt is where the project says build and run directions live, and the Makefile confirms the toolchain assumption: this is a Visual Studio command-line build, not a CMake project.

From a Visual Studio developer command prompt at the repository root, the Makefile's default all target is the entry point. Its all target reads:

all:
    cd "$(MAKEDIR)"
    @if exist "$(MAKEDIR)\core\makefile" cd "$(MAKEDIR)\core" && $(MAKE) /NOLOGO /$(MAKEFLAGS)
    cd "$(MAKEDIR)\src"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS)
    cd "$(MAKEDIR)\samples"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS)
    cd "$(MAKEDIR)\tests"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS)

The all target changes into src, then samples, then tests, invoking $(MAKE) in each. If the build succeeds you end up with libraries and sample binaries under the output directories that system.mak defines. To remove the intermediate files afterwards, the same Makefile provides a clean target, which repeats those directory changes with a clean argument:

clean:
    cd "$(MAKEDIR)"
    @if exist "$(MAKEDIR)\core\makefile" cd "$(MAKEDIR)\core" && $(MAKE) /NOLOGO /$(MAKEFLAGS) clean
    cd "$(MAKEDIR)\src"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS) clean
    cd "$(MAKEDIR)\samples"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS) clean
    cd "$(MAKEDIR)\tests"
    @$(MAKE) /NOLOGO /$(MAKEFLAGS) clean

The realclean target goes further and also removes the include, library and binary output directories along with a dist directory. The realclean target also deletes docsrc\detours.chm and any .msi files.

A first real use: start from the simple sample, not the library

The fastest way to understand Detours is to build one sample and read it. The samples directory contains a README.txt with directions for building and running samples, and simple and simple_safe are the smallest starting points.

The samples are not toys in the sense of being unrelated to the library: each one exercises a specific interception pattern, and the names are descriptive enough to pick by intent. simple and simple_safe are the natural pair to read first; samples/README.TXT describes the rest.

What you should see after a successful build is a set of working executables that demonstrate interception in isolation. Treat the samples as the tutorial the README does not contain. The README defers to samples/README.TXT for build and run directions, and that file is the authoritative first-use guide.

Where Detours is the wrong tool

The hard boundary is stated plainly in the README: Detours cannot be used by Windows Store apps because it requires APIs not available to those applications. If your target is a packaged UWP application, stop here. No amount of build configuration changes that, because the restriction comes from the application model rather than from the library's build.

A second limitation is the release situation. The repository contains the source for version 4.0.1, and the most recent release listed is v4.0.1 from 2018-04-16. The last push to the repository was on 2026-10-14, so work is happening in the tree, but there is no newer tagged release to point at. If your process requires pinning to a released version with a changelog, you are pinning to something from 2018 and taking the rest from main. That is a legitimate reason to look elsewhere, and it is worth knowing before you write Detours into a build plan.

A third constraint is toolchain and platform coupling. The build is nmake-based and depends on system.mak resolving correctly against your Visual Studio installation. The README lists NT-family operating systems up to Windows 11, so the target range is broad, but the build environment is not: this is a Windows-only, MSVC-oriented project with no cross-platform build files in the repository listing.

Alternatives and how their approach differs

The clearest alternative in the same problem space is a hooking library that ships as a prebuilt package with a package manager, rather than as source you compile yourself. Microsoft Detours gives you the source, an nmake build, and a set of samples that you adapt; a packaged hooking library gives you a binary and an API surface to call. The difference shows up in the first hour: with Detours you spend it getting nmake and system.mak to agree with your Visual Studio installation, and with a packaged library you spend it reading an API reference.

The trade runs the other way too. Because Detours is source, you can read every line of the interception logic and build it against your own toolchain, which matters when the detoured code sits inside a product. A binary distribution gives you less to audit. Detours also carries Microsoft's own usage as context, which a smaller library cannot claim. Neither approach is universally better; the question is whether you want to own a build or own a dependency.

If your requirement is narrower, a smaller library may be less work.

Licence, maintenance and the cost of upgrading

Detours is licensed under MIT. The README states that the move to a standard open source licence simplifies licensing for programmers using Detours, and the repository carries both LICENSE and LICENSE.md at the top level. MIT is permissive, which generally means you can use, modify and redistribute the code with the licence and copyright notice preserved, but the specific obligations depend on how you ship the detoured binary and what notices you already carry. That is a question for your own counsel, not something the README settles.

Upgrade cost is dominated by the release gap. The most recent release is v4.0.1 from 2018-04-16, and the repository's last push was on 2026-10-14, so the source tree has moved on without a corresponding tag. Anyone tracking fixes is effectively tracking main. For a library that patches function entry points inside a process, that is a meaningful consideration: the code you build is the code you must test, and the samples and tests directories are the only verification surface the repository provides.

Most contributions require a Contributor License Agreement, and the README notes that a CLA bot decorates pull requests automatically. That matters if you intend to send patches upstream rather than vendor a fork.

Editorial conclusion

Adopt Detours when you control the target process and need to intercept Win32 calls in a Windows desktop or server binary, and you accept building the library from source with the Visual Studio toolchain. Do not adopt it for Windows Store (UWP) applications, since the README states Detours requires APIs those apps cannot call, and do not expect a prebuilt package or a release cadence: the repository carries version 4.0.1 and the most recent release is from 2018-04-16. Before you commit, verify that the sample set matching your scenario builds and runs on your target OS, and confirm the MIT terms in LICENSE.md cover how you intend to redistribute the detoured binary.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/Detours on GitHub
4. README
5. Releases