Req v0.1.0

Req.mojo 0.1.0

Req is a synchronous HTTP/1.1 client for Mojo. Send HTTP requests, work with JSON, and reuse connections through a persistent Client using a familiar, explicit API.

What you can do

• Send GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS requests with query parameters and headers.
• Submit JSON, form fields, or raw bytes; read response bodies as bytes, text, or JSON.
• Reuse connections, default headers, authentication, and cookies with Client.
• Stream large response bodies and decode gzip/deflate responses.
• Configure connect/read/write timeouts, Basic or Bearer authentication, redirects, and custom CA certificates. TLS verification is enabled by default; redirects are opt-in.
• Handle typed HTTP, connection, timeout, decoding, and request errors.

Install with Pixi

From a Pixi workspace configured for Mojo, add the official Modular Community channel and install Req:

pixi workspace channel add --prepend https://repo.prefix.dev/modular-community
pixi add req

The community recipe is awaiting review. These commands become available once the package is published to the channel. While it is under review, use the precompiled downloads or source build below.

Req 0.1.0 uses Mojo 1.1.0. Pixi resolves the matching compiler, libcurl, and zlib. The package includes req.mojoc, the required CPU JSON modules, and a prebuilt native shared library. Req loads the transport automatically from the active Pixi environment; no C compilation or extra linker flags are needed.

Send your first request

Save this as main.mojo in your workspace root:

import req


def main() raises:
    var response = req.get("https://example.com")
    response.raise_for_status()
    print(response.status_code)
    print(response.headers["Content-Type"])
    print(response.text())

Run it directly:

pixi run mojo main.mojo

Or compile and run inside the Pixi environment:

pixi run mojo build main.mojo -o main
pixi run ./main

Reuse a client and read JSON

For repeated requests, a Client shares connections and defaults. Replace main.mojo with:

import req


def main() raises:
    var owner = req.Client(
        base_url="https://httpbin.org/",
        headers=req.Headers({"Accept": "application/json"}),
        timeout=req.Timeout(10.0),
    )
    with owner.context() as client:
        var response = client.get("get", params=req.QueryParams({"hello": "mojo"}))
        response.raise_for_status()
        print(response.json().to_string())
        var second = client.get("headers")
        second.raise_for_status()
        print(second.json().to_string())

Run it with the same pixi run mojo main.mojo command. The context closes the client when the block exits, including on errors. Each client is intended for single-threaded use.

Use a precompiled download

Release assets are provided for Linux x86-64, Linux ARM64, and macOS ARM64, all built with Mojo 1.1.0. Download the archive matching your machine and verify it against SHA256SUMS. Each archive includes req.mojoc, libreq_curl.so (Linux) or libreq_curl.dylib (macOS), the license, and the pinned Pixi environment files.

Install libcurl 7.85+ with TLS support and zlib (provided by macOS; libcurl4t64 zlib1g on Ubuntu 24.04), extract the archive, and enter its directory. Run pixi install --locked, save the first example as main.mojo, and run:

pixi run mojo -I . main.mojo

Req loads the shared library in the extracted directory. Keep the archive's compiler version and platform matched to your environment.

Build from source

Source builds require Pixi, a C compiler, libcurl 7.85+ development headers with TLS support, and zlib development headers. Install Command Line Tools on macOS, or build-essential libcurl4-openssl-dev zlib1g-dev openssl on Debian/Ubuntu, then:

git clone --branch v0.1.0 --depth 1 https://github.com/mojoto/req.mojo.git
cd req.mojo
pixi install
make build

Save the first example as main.mojo in the repository root, then:

pixi run mojo -I . main.mojo

Req finds the native library built by make build in build/.

Learn more

• Getting started
• Requests, JSON, authentication, and responses
• Persistent clients and cookies
• Streaming
• Error handling

This is the first release. Req currently provides a synchronous API; HTTP/2, HTTP/3, and an async API are outside this release's scope.