# What is ConPTY in Windows Terminal? The Windows Pseudo-Console API Explained

> Learn about ConPTY, the Windows Pseudo-Console API enabling modern terminal applications to host command-line tools and break free from legacy constraints.

- Repository: [Microsoft/terminal](https://github.com/microsoft/terminal)
- Tags: deep-dive
- Published: 2026-02-26

---

**ConPTY (Pseudo-Console) is a Windows 10/Server 2019 API that enables applications to create headless console sessions and communicate via anonymous pipes, allowing Windows Terminal to host traditional command-line tools in modern tabbed interfaces without legacy console window constraints.**

ConPTY revolutionized terminal emulation on Windows by providing a bridge between legacy console applications and modern UI frameworks. In the `microsoft/terminal` repository, ConPTY serves as the foundational layer that powers every tab, enabling processes like PowerShell, WSL, and cmd.exe to run inside Windows Terminal's hardware-accelerated interface while maintaining full compatibility with standard console APIs.

## Understanding the ConPTY Architecture

The ConPTY implementation in Windows Terminal consists of three distinct layers that handle everything from low-level handle management to high-level UI integration.

### Low-Level ConPTY Library

At the foundation, the **low-level ConPTY library** wraps the native Windows APIs `CreatePseudoConsole`, `ResizePseudoConsole`, and `ShowHidePseudoConsole`. This layer manages the three critical handles defined in [`src/winconpty/winconpty.h`](https://github.com/microsoft/terminal/blob/main/src/winconpty/winconpty.h):

- `hSignal` – Anonymous pipe for out-of-band control messages (resize, show/hide, clear)
- `hPtyReference` – Reference handle keeping the underlying `conhost.exe` process alive
- `hConPtyProcess` – Handle to the `conhost.exe` process hosting the pseudo-console

The implementation in [`src/winconpty/winconpty.cpp`](https://github.com/microsoft/terminal/blob/main/src/winconpty/winconpty.cpp) provides thin C-style wrappers like `ConptyCreatePseudoConsoleAsUser` that the rest of the codebase consumes.

### ConPTY Connection Layer

The **ConPTY connection layer** implements the `ITerminalConnection` interface used by Windows Terminal's UI. Defined in [`src/cascadia/TerminalConnection/ConptyConnection.h`](https://github.com/microsoft/terminal/blob/main/src/cascadia/TerminalConnection/ConptyConnection.h) and implemented in the matching `.cpp` file, this layer:

- Manages the pseudo-console lifecycle from creation to destruction
- Launches child processes (cmd, PowerShell, WSL) with the appropriate attribute lists
- Forwards input/output between the UI and the pseudo-console pipes
- Handles resize and focus events via the signal pipe
- Propagates VT-sequence signals back to the host

### Sample Implementations

For developers building custom applications, the repository provides a managed wrapper in [`samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs`](https://github.com/microsoft/terminal/blob/main/samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs). This sample demonstrates creating pipes, starting a pseudo-console, and reading/writing VT-aware streams without requiring the full Windows Terminal UI framework.

## Creating and Managing Pseudo-Consoles

The process of establishing a ConPTY session involves several precise steps to ensure proper handle inheritance and process isolation.

### Initializing the Pseudo-Console

Windows Terminal creates a pseudo-console by calling `ConptyCreatePseudoConsoleAsUser` from [`src/winconpty/winconpty.h`](https://github.com/microsoft/terminal/blob/main/src/winconpty/winconpty.h):

```cpp
HRESULT WINAPI ConptyCreatePseudoConsoleAsUser(
    HANDLE hToken, COORD size,
    HANDLE hInput, HANDLE hOutput,
    DWORD dwFlags, HPCON* phPC);

```

This function returns an `HPCON` handle and populates a `PseudoConsole` structure containing the three critical handles. The `hToken` parameter allows running the console under a specific user context, while `hInput` and `hOutput` are the anonymous pipe handles for VT-encoded data streams.

### Handle Inheritance and Process Lifetime

A critical aspect of ConPTY is handle inheritance. The `hPtyReference` handle is duplicated into the child process via `CreateProcess` using the `PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE` attribute. This ensures the pseudo-console stays alive even if the parent (Windows Terminal) terminates unexpectedly—the reference count only drops to zero when all client processes exit.

```cpp
STARTUPINFOEXW siEx = { sizeof(siEx) };
size_t attrSize = 0;
InitializeProcThreadAttributeList(nullptr, 1, 0, &attrSize);
siEx.lpAttributeList = reinterpret_cast<LPPROC_THREAD_ATTRIBUTE_LIST>(HeapAlloc(GetProcessHeap(), 0, attrSize));
InitializeProcThreadAttributeList(siEx.lpAttributeList, 1, 0, &attrSize);
UpdateProcThreadAttribute(siEx.lpAttributeList,
                         0,
                         PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,
                         hPc,
                         sizeof(hPc),
                         nullptr,
                         nullptr);

CreateProcessW(L"C:\\Windows\\System32\\cmd.exe",
               nullptr, nullptr, nullptr, FALSE,
               EXTENDED_STARTUPINFO_PRESENT, nullptr,
               nullptr, &siEx.StartupInfo, &pi);

```

## VT-Aware I/O and Signal Handling

ConPTY operates entirely through VT-encoded streams, enabling modern terminal features while maintaining backward compatibility.

### The Signal Pipe Architecture

Control messages flow through the `hSignal` pipe defined in [`src/winconpty/winconpty.h`](https://github.com/microsoft/terminal/blob/main/src/winconpty/winconpty.h). ConPTY sends signals such as `PTY_SIGNAL_SHOW_HIDE_WINDOW`, `PTY_SIGNAL_CLEAR`, and `PTY_SIGNAL_RESIZE_WINDOW` through this out-of-band channel. The `ConptyConnection` class reads this pipe on a dedicated signal thread and updates the UI accordingly, as implemented in [`src/host/VtIo.cpp`](https://github.com/microsoft/terminal/blob/main/src/host/VtIo.cpp) and [`src/cascadia/TerminalConnection/ConptyConnection.cpp`](https://github.com/microsoft/terminal/blob/main/src/cascadia/TerminalConnection/ConptyConnection.cpp).

### Handling Resize and Focus Events

When a user resizes a Windows Terminal tab, the `ConptyConnection::Resize` method calls `_ResizePseudoConsole` to update the pseudo-console dimensions:

```cpp
void ConptyConnection::Resize(uint32_t rows, uint32_t columns)
{
    _rows = rows;
    _cols = columns;
    _ResizePseudoConsole(_hPC.get(), { static_cast<SHORT>(columns), static_cast<SHORT>(rows) });
}

```

Similarly, focus changes trigger `ShowHide` or `ReparentWindow` signals that propagate through the signal pipe to `conhost.exe`, ensuring the child process receives accurate focus state notifications via standard console APIs.

### State Machine Integration

All VT sequences flowing through ConPTY are parsed by Windows Terminal's **StateMachine**, implemented in [`src/terminal/parser/stateMachine.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/stateMachine.cpp). This component translates incoming VT streams into rendering operations while forwarding specific sequences (such as focus events) back to ConPTY via the signal pipe, creating a bidirectional communication channel.

## Why ConPTY Matters for Windows Terminal

ConPTY provides three critical advantages that enable Windows Terminal to function as a modern, high-performance terminal emulator.

**Process Isolation** – Each tab runs inside its own `conhost.exe` process via ConPTY. If a child application crashes or hangs, it cannot bring down the entire Windows Terminal instance or affect other tabs.

**Performance Optimization** – By bypassing the legacy Console API and delivering raw VT streams directly through anonymous pipes, ConPTY eliminates extra translation layers. The terminal receives VT-encoded data that maps directly to modern GPU-accelerated rendering pipelines.

**Backward Compatibility** – Because ConPTY hosts child processes inside genuine `conhost.exe` instances, all standard Windows console APIs (such as `ReadConsoleInput`, `SetConsoleMode`, and `WriteConsole`) continue to function exactly as legacy applications expect. The UI layer gains full VT support while maintaining compatibility with decades of existing command-line tools.

## Summary

- **ConPTY** is the Windows 10/Server 2019 Pseudo-Console API that enables headless console sessions via anonymous pipes.
- Windows Terminal uses ConPTY to host each tab in an isolated `conhost.exe` process, implementing the `ITerminalConnection` interface through `ConptyConnection`.
- The architecture consists of three layers: the low-level `winconpty` library wrapping native APIs, the C++/WinRT connection layer managing lifecycle and I/O, and sample implementations demonstrating managed usage.
- Critical implementation details include the three-handle structure (`hSignal`, `hPtyReference`, `hConPtyProcess`), VT-encoded I/O streams, and signal pipe architecture for resize/focus events.
- ConPTY provides process isolation, performance improvements through raw VT streams, and full backward compatibility with legacy console APIs.

## Frequently Asked Questions

### What is the difference between ConPTY and traditional console APIs?

Traditional Windows console applications interact with the console subsystem through the Console API (functions like `ReadConsole` and `WriteConsole`), which requires a visible console window or complex workarounds for headless operation. **ConPTY** provides a modern, headless alternative that uses anonymous pipes for VT-encoded input/output, allowing terminal emulators to host console applications without creating visible console windows while maintaining full API compatibility through the underlying `conhost.exe` process.

### Is ConPTY available on all Windows versions?

ConPTY was introduced in **Windows 10 version 1809** (October 2018 Update) and Windows Server 2019. It is not available on earlier Windows versions such as Windows 8.1 or Windows 7. Applications attempting to use ConPTY APIs on unsupported systems will receive error codes from the `CreatePseudoConsole` function and should fall back to traditional console hosting methods.

### How does ConPTY handle process isolation?

ConPTY achieves process isolation by hosting each pseudo-console inside a separate `conhost.exe` process. When Windows Terminal creates a new tab, it initializes a ConPTY session that spawns a dedicated `conhost.exe` instance via the `ConptyCreatePseudoConsoleAsUser` function. The `hPtyReference` handle maintains a reference count on this process, ensuring that even if the terminal crashes, the console session persists until the child application exits. This architecture prevents a single misbehaving application from crashing the entire terminal emulator.

### Can I use ConPTY in my own applications?

Yes, Microsoft provides the ConPTY API as a public Windows API surface, and the `microsoft/terminal` repository includes sample implementations demonstrating integration. Developers can use the native Windows API functions (`CreatePseudoConsole`, `ResizePseudoConsole`, `ClosePseudoConsole`) directly, or reference the [`samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs`](https://github.com/microsoft/terminal/blob/main/samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs) file for a managed C# implementation. The key requirements are Windows 10 version 1809 or later, and proper handle management for the input/output pipes and signal channel.