---
url: /httpx.zig/guide/getting-started.md
---
# Getting Started

`httpx.zig` is a modern, feature-rich HTTP library for the Zig programming language. It is under active development, supporting robust client and server implementations with focus on performance and developer experience.

## Features

* **Protocol Support**: HTTP/1.0/1.1/2/3 client/server runtime paths plus full HTTP/2 and HTTP/3 protocol primitives.
* **Cross-Platform**: Validated on Linux, Windows, and macOS with x86\_64, aarch64, and x86 architectures.
* **Client**:
  * Connection pooling and keep-alive.
  * Automatic retries with exponential backoff.
  * Request/Response interceptors.
  * Cookie management.
  * Idiomatic, grouped configuration structs with sensible defaults.
* **Server**:
  * Pattern-based routing.
  * Middleware architecture.
  * Static file serving.
  * JSON helpers.
* **Concurrency**: Built-in thread pool and async primitives (`all`, `any`, `race`).
* **Security**: Custom TLS 1.2/1.3 implementation with ALPN negotiation, ECDSA certificate verification, and custom CA handling.
* **Modern Architecture**: Minimal, unified client and server APIs, explicit resource ownership, and zero boilerplate.

::: warning Custom HTTP/2, HTTP/3, and TLS Implementation
Zig's standard library does not provide HTTP/2, HTTP/3, QUIC, or TLS/ALPN support. **httpx.zig implements these protocols entirely from scratch**, including:

* **TLS 1.2 and 1.3** with full handshake support (RFC 5246 / RFC 8446) — key exchange: X25519; AEAD cipher suites: ChaCha20-Poly1305, AES-128-GCM, AES-256-GCM; ALPN negotiation (RFC 7301); X.509 certificate parsing and verification (client-side)
* **HPACK** header compression (RFC 7541) with `Without Indexing` / `Never Indexed` security for HTTP/2
* **HTTP/2** stream multiplexing, flow control (WINDOW\_UPDATE), SETTINGS enforcement, GOAWAY/RST\_STREAM, PRIORITY, CONTINUATION frames, PING, and connection pooling (RFC 7540)
* **QPACK** header compression (RFC 9204) with static/dynamic tables and decoder/encoder stream instructions for HTTP/3
* **QUIC** transport frame encoding/decoding (RFC 9000) with RESET\_STREAM/STOP\_SENDING cancellation, version negotiation, and transport parameters
* **HTTP/3** frame types, SETTINGS, GOAWAY, and CONNECTION\_CLOSE handling
  :::

## Requirements

* **Zig Version**: 0.16.0 or later
* **Operating System**: Windows, Linux, or macOS

::: warning Upgrading from 0.1.x
v0.2.0 is a breaking release (Zig `0.16.0` required) with no
compatibility wrappers. Review the updated Client/Server/Router usage
in this guide when migrating from any `0.1.x` (or older).
:::

## Platform Support

### Operating Systems

| Platform | Status | Notes |
|----------|--------|-------|
| Linux    | ✅ Full | All major distributions (Ubuntu, Debian, Fedora, Arch, etc.) |
| Windows  | ✅ Full | Windows 10/11, Server 2019+ |
| macOS    | ✅ Full | macOS 11+ (Big Sur and later) |

### Architectures

| Architecture | Linux | Windows | macOS | Notes |
|--------------|-------|---------|-------|-------|
| x86\_64 (64-bit) | ✅ | ✅ | ✅ | Primary development target |
| aarch64 (ARM64) | ✅ | ✅ | ✅ | Apple Silicon, AWS Graviton, Raspberry Pi 4+ |
| x86 (32-bit) | ✅ | ✅ | ❌ | Legacy x86 support on Linux/Windows |

### Cross-Compilation

Zig's built-in cross-compilation makes it easy to build for any target:

```bash
# Build for Linux x86_64
zig build -Dtarget=x86_64-linux

# Build for Linux ARM64
zig build -Dtarget=aarch64-linux

# Build for Windows x86_64
zig build -Dtarget=x86_64-windows

# Build for Windows x86 (32-bit)
zig build -Dtarget=x86-windows

# Build for macOS ARM64 (Apple Silicon)
zig build -Dtarget=aarch64-macos

# Build for macOS x86_64 (Intel)
zig build -Dtarget=x86_64-macos
```

## Next Steps

* Check out the [Installation](/guide/installation) guide to add `httpx.zig` to your project.
* Learn how to make [Basic Requests](/guide/client-basics) with the client.
* Set up a simple [Server](/guide/routing).
* Explore [HTTP/2](/guide/http2) and [HTTP/3](/guide/http3) protocol support.
* Review [API Overview](/api/) for explicit root exports and aliases.