# turboAPI puts a Zig HTTP core under FastAPI style routes

> TurboAPI is a Python web framework that keeps FastAPI's decorator style and swaps the server for a compiled Zig core, aimed at HTTP-only workloads on free-threaded Python 3.14. The readme is unusually honest about what is missing, including TLS, a configurable body limit and alpha WebSocket support, and it requires a reverse proxy in front of it.

**justrach/turboAPI** — FastAPI-compatible Python framework with Zig HTTP core; 7x faster, free-threading native

- Repository: https://github.com/justrach/turboAPI
- Website: https://turboapi.trilok.ai
- Stars: 1,010 · Forks: 28
- Language: Zig
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/justrach-turboapi

## The decorators stay, the server changes

TurboAPI describes itself as a FastAPI-compatible Python framework with a Zig HTTP core, and the pitch line in the readme is specific about the scope: faster on HTTP-only and uncached HTTP+DB workloads.

The compatibility is at the API level. You import TurboAPI instead of FastAPI, you define your models with dhi's BaseModel, and your route decorators look the same:

```python
from turboapi import TurboAPI
from dhi import BaseModel

app = TurboAPI()

class Item(BaseModel):
    name: str
    price: float
    quantity: int = 1

@app.get("/")
def hello():
    return {"message": "Hello World"}

@app.post("/items")
def create_item(item: Item):
    return {"item": item.model_dump(), "created": True}
```

What changes underneath is the server. The readme's feature table lists a Zig HTTP server with a 24 thread pool and keep-alive, Zig-native JSON schema validation through dhi, a zero-alloc response pipeline using stack buffers, Zig-native CORS with pre-rendered headers and zero overhead, response caching for handlers with no arguments, and static routes pre-rendered at startup.

There is also a path that skips Python entirely. Native FFI handlers written in C or Zig are listed as supported, which means a hot endpoint can be compiled and called without the interpreter in the loop at all.

The primary language of the repository is Zig, with the core in the turboapi-core directory and the zig directory, and the Python package lives under python. The licence is MIT, the package on PyPI is turboapi, and the project site is turboapi.trilok.ai.

## The feature table is honest about the gap between today and the roadmap

The readme contains a two column table, What works today and What's in progress, and the in progress column is unusually specific.

What is in progress is native HTTP/2, HTTP/3 and QUIC, and TLS. There is a Cloudflare Workers WASM target. There is fiber-based concurrency, via a separate project called zag. And there is higher-density evented WebSocket scaling.

What works today is a long list: roughly 140k requests per second on uncached HTTP routes, FastAPI-compatible route decorators, the Zig HTTP server with the 24 thread pool and keep-alive, Zig-native JSON schema validation, the zero-alloc response pipeline, Zig-native CORS, response caching for noargs handlers, pre-rendered static routes, async handler support, a full security stack with OAuth2, Bearer and API Key, Python 3.14t free-threaded support, native FFI handlers, bounded full-duplex WebSocket isolation which is marked alpha, and a fuzz-tested HTTP parser, router and validator.

Reading the table as a whole tells you the shape of the project. The HTTP request path is finished and hardened, with fuzz testing on the parser, the router and the validator. The long-lived connection path is not. The protocol negotiation path is not. What is done is the part where a request arrives, is validated, is routed, is executed and is returned, and that is a coherent thing to have finished first.

The status badge says Alpha, and the readme says it plainly, that this is alpha software and to read before using in production. The pyproject classifiers say Beta, and the version is 1.0.35, which is a version number that reads as stable. Those three signals disagree, and the readme is the one to trust.

## The alpha warnings are the real documentation

The Status section of the readme is the most useful part of the project, because it lists what will break your deployment before you find out in production.

There is no native TLS, HTTP/2, HTTP/3 or QUIC, so the guidance is to put Caddy with Let's Encrypt, nginx, cloudflared, Cloudflare, or another edge proxy in front for HTTPS and modern protocols. In other words, this server does not terminate TLS, and a deployment that expects it to is going to be disappointed.

There is basic slow-loris protection through a 30 second read timeout, but the documentation says production deployments should still use a reverse proxy with stricter limits. There is no configurable max body size, with a hardcoded 16MB cap, which is a real constraint for an API that accepts uploads.

Zig-native WebSocket support is available but still alpha. The routes are exact-match, a synchronous route guard can reject an Authorization or Origin policy before the 101 response, but the post-upgrade handler cannot, and accepted connections transfer to a bounded dedicated pool with bounded duplex queues so that they do not retain HTTP workers. Keep an authenticating edge such as Cloudflare Access as the outer security boundary.

And free-threaded Python 3.14t is itself relatively new, so some C extensions may not be thread safe.

That last point deserves emphasis for anyone with a dependency tree. The whole design depends on the absence of the GIL, and free-threading is new enough that a single non thread safe C extension in your dependency chain removes the benefit for that request.

## Two ways to run it, and one of them is a fallback

The quick start offers Docker as the easiest option, and the local install as the other one.

The Docker path is three commands:

```bash
git clone https://github.com/justrach/turboAPI.git
cd turboAPI
docker compose up
```

That builds Python 3.14t from source, compiles the Zig backend, and runs the example app, and you hit http://localhost:8000 to verify. The compose file is minimal, a single service built from the repository with the port 8000 published and one environment variable, TURBO_DISABLE_RATE_LIMITING=1, which is there so the benchmark and example traffic is not throttled.

The local path is:

```bash
uv python install 3.14t
pip install turboapi
```

and then you run your app with the free-threaded interpreter:

```bash
python3.14t app.py
# 🚀 TurboNet-Zig server listening on 127.0.0.1:8000
```

The requirements are Python 3.14 or newer free-threaded, that is 3.14t, and Zig 0.17.0-dev.1862+40ebd8162. The project pins that exact Zig nightly across its manifest, CI, release, Docker and native build tooling, and the Dockerfile downloads the Zig archive and checks a sha256 for it per architecture before extracting it.

There is also a third path that the readme explicitly labels as a fallback. The app exposes an ASGI __call__, so you can use uvicorn main:app to test your route definitions before building the native backend, but this is pure-Python and much slower, and for production the documentation says always use app.run() with the compiled Zig backend.

## The speed claims disagree with each other

Three different performance claims appear in the project's own files, and they do not match.

The repository description says FastAPI-compatible Python framework with Zig HTTP core, 7x faster, free-threading native. The readme's feature table says roughly 140k requests per second on uncached HTTP routes, which it annotates as about 16x FastAPI. And the description in the project metadata, the one that appears on PyPI, says FastAPI-compatible web framework with Zig HTTP core, 20x faster with Python 3.14 free-threading.

Seven, sixteen and twenty. All three are in the same repository, and a reader has no way to tell from the files which comparison each one refers to. The readme's own benchmarking section is linked from the table of contents, and the repository has a benches directory, a benchmarks directory, and an examples folder with a database benchmark, a SIMD benchmark, a complex database test and a compose file for benchmarks, so the measurement infrastructure is there. It is the summary claim that is inconsistent.

There is a more important point underneath the numbers, and the readme states it in the feature table heading and in the benchmark section title. The gains are scoped. Faster on HTTP-only and uncached HTTP+DB workloads is a narrow claim, and it makes sense: a request that is a static route, a cached response or a validation error never reaches a Python handler, so the interpreter is out of the path entirely. A request that does database work spends most of its time waiting for the database, and no amount of server-side speed helps much there.

So the honest way to read this project is that it is optimised for a specific shape of workload, and the evaluation you should run is your own workload rather than a request per second figure from a table.

## Packaging that knows whether the native build happened

The packaging arrangement in the repository is a small lesson in how to ship a binary extension.

The setup.py file is described in its own docstring as a setuptools compatibility shim for the prebuilt Zig extension, and it contains a custom Distribution subclass. The has_ext_modules method looks into the python/turboapi package directory and returns true only if it finds a turbonet shared object on Linux and macOS or a turbonet pyd on Windows. The effect is that a wheel is marked as containing a binary extension only after the Zig extension has actually been built, so a pure Python wheel cannot be published by accident.

The project metadata declares requires-python >=3.14 and a single runtime dependency, dhi at 1.1.15 or newer, the model layer used in the readme's examples. The package data section lists the.so,.dylib and.pyd files, and the packages are found under the python directory. The optional dependency groups are tidy: dev with pytest, pytest-asyncio, websockets, ruff and mypy; benchmark with aiohttp, matplotlib and requests; jwt and auth with PyJWT, cryptography, and passlib with bcrypt for the auth extra.

The build system in the Dockerfile is the heavy part. It starts from python:3.14.7-bookworm, pins the interpreter source with a sha256 and explains why, that the root image is used by latency-sensitive deployments and silently following a mutable Python tag is unsafe. It then builds the free-threaded interpreter with reproducible profile guided optimisation and full link time optimisation on both amd64 and arm64, with a comment explaining that BOLT is deliberately not required because Debian's native GCC toolchain already supports that on both architectures.

The release history in the readme shows the discipline is still being built. Version 1.0.27 was re-cut after bad 1.0.25 and 1.0.26 publishes and added release guardrails so tag pushes fail on version drift, and 1.0.26 was itself a re-cut after 1.0.25 published stale 1.0.24 artefacts. Three releases in a day on 2026-08-26, v1.0.33, v1.0.34 and v1.0.35, suggest the pace has picked up since.

## Conclusion

turboAPI is worth following if you run an HTTP-only API on free-threaded Python and the per request overhead of a pure Python server is your bottleneck, because the shape of the project, a Zig HTTP core behind FastAPI compatible routes, is the right shape for that problem. It is the wrong choice for production today, because the project says so itself, there is no native TLS so an edge proxy is required, and the body size limit is hardcoded. Before you try it, read SECURITY.md rather than the readme alone, confirm your C extensions are thread safe on 3.14t, and note that the newest release is v1.0.35 from 2026-08-26 with the repository pushed to on 2026-10-19, and that the project publishes three different speed claims for itself.

## FAQ

### What is turboAPI and is it a drop-in replacement for FastAPI?

It is a FastAPI-compatible Python framework with a Zig HTTP core. The route decorators and the model style stay the same, with models defined through dhi's BaseModel, while the server, validation, CORS and response pipeline are implemented in Zig. The readme still labels the project alpha software and recommends reading it before using it in production.

### What does turboAPI require to run?

Python 3.14 or newer in its free-threaded form, 3.14t, and Zig 0.17.0-dev.1862+40ebd8162, with that exact nightly pinned across the manifest, CI, release, Docker and native build tooling. The local install uses uv python install 3.14t followed by pip install turboapi, and the Docker path builds the interpreter from source.

### Does turboAPI handle TLS and HTTP/2 itself?

No. The readme lists native TLS, HTTP/2, HTTP/3 and QUIC as in progress, and says to put Caddy with Let's Encrypt, nginx, cloudflared, Cloudflare or another edge proxy in front for HTTPS and modern protocols. There is also a hardcoded 16MB body size limit with no configurable option.

### Can I run a turboAPI app with uvicorn?

The app exposes an ASGI __call__ fallback, so uvicorn main:app works for testing route definitions before building the native backend. The readme notes this path is pure Python and much slower, and that for production you should always use app.run() with the compiled Zig backend.

### How fast is turboAPI compared to FastAPI?

The project publishes three different figures in its own files, 7x faster in the repository description, about 16x in the readme feature table for roughly 140k requests per second on uncached HTTP routes, and 20x in the PyPI project description. The claim is also scoped to HTTP-only and uncached HTTP+DB workloads, so your own workload is the measurement that counts.

## Sources

- [justrach/turboAPI on GitHub](https://github.com/justrach/turboAPI)
- [License: MIT](https://github.com/justrach/turboAPI/blob/main/LICENSE)
- [Project website](https://turboapi.trilok.ai)
- [README](https://github.com/justrach/turboAPI/blob/main/README.md)
- [Releases](https://github.com/justrach/turboAPI/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/justrach-turboapi