ureq

A simple, safe HTTP client.

Ureq's first priority is being easy for you to use. It's great for anyone who wants a low-overhead HTTP client that just gets the job done. Works very well with HTTP APIs. Its features include cookies, JSON, HTTP proxies, HTTPS, charset decoding, and is based on the API of the http crate.

Ureq is in pure Rust for safety and ease of understanding. It forbids unsafe code. It uses blocking I/O instead of async I/O, because that keeps the API simple and keeps dependencies to a minimum. For TLS, ureq uses rustls or native-tls.

See the changelog for details of recent releases.

Usage

In its simplest form, ureq looks like this:

let body: String = ureq::get("http://example.com")
    .header("Example-Header", "header value")
    .call()?
    .body_mut()
    .read_to_string()?;

For more involved tasks, you'll want to create an [Agent]. An Agent holds a connection pool for reuse, and a cookie store if you use the cookies feature. An Agent can be cheaply cloned due to internal [Arc] and all clones of an Agent share state among each other. Creating an Agent also allows setting options like the TLS configuration.

use ureq::Agent;
use std::time::Duration;

let mut config = Agent::config_builder()
    .timeout_global(Some(Duration::from_secs(5)))
    .build();

let agent: Agent = config.into();

let body: String = agent.get("http://example.com/page")
    .call()?
    .body_mut()
    .read_to_string()?;

// Reuses the connection from previous request.
let response: String = agent.put("http://example.com/upload")
    .header("Authorization", "example-token")
    .send("some body data")?
    .body_mut()
    .read_to_string()?;

JSON

Ureq supports sending and receiving json, if you enable the json feature:

use serde::{Serialize, Deserialize};

#[derive(Serialize)]
struct MySendBody {
   thing: String,
}

#[derive(Deserialize)]
struct MyRecvBody {
   other: String,
}

let send_body = MySendBody { thing: "yo".to_string() };

// Requires the `json` feature enabled.
let recv_body = ureq::post("http://example.com/post/ingest")
    .header("X-My-Header", "Secret")
    .send_json(&send_body)?
    .body_mut()
    .read_json::<MyRecvBody>()?;

Error handling

ureq returns errors via Result<T, ureq::Error>. That includes I/O errors, protocol errors. By default, also HTTP status code errors (when the server responded 4xx or 5xx) results in [Error].

This behavior can be turned off via [http_status_as_error()]

use ureq::Error;

match ureq::get("http://mypage.example.com/").call() {
    Ok(response) => { /* it worked */},
    Err(Error::StatusCode(code)) => {
        /* the server returned an unexpected status
           code (such as 400, 500 etc) */
    }
    Err(_) => { /* some kind of io/transport/etc error */ }
}

Features

To enable a minimal dependency tree, some features are off by default. You can control them when including ureq as a dependency.

ureq = { version = "3", features = ["socks-proxy", "charset"] }

The default enabled features are: rustls and gzip.

rustls enables the rustls TLS implementation. This is the default for the the crate level convenience calls (ureq::get etc). It currently uses ring as the TLS provider.
native-tls enables the native tls backend for TLS. Due to the risk of diamond dependencies accidentally switching on an unwanted TLS implementation, native-tls is never picked up as a default or used by the crate level convenience calls (ureq::get etc) – it must be configured on the agent
platform-verifier enables verifying the server certificates using a method native to the platform ureq is executing on. See [rustls-platform-verifier] crate
socks-proxy enables proxy config using the socks4://, socks4a://, socks5:// and socks:// (equal to socks5://) prefix
cookies enables cookies
gzip enables requests of gzip-compressed responses and decompresses them
brotli enables requests brotli-compressed responses and decompresses them
charset enables interpreting the charset part of the Content-Type header (e.g. Content-Type: text/plain; charset=iso-8859-1). Without this, the library defaults to Rust's built in utf-8
json enables JSON sending and receiving via serde_json
multipart enables multipart/form-data sending via [unversioned::multipart]
rustls-webpki-roots enables the webpki-roots crate for root certificates when using rustls.
native-tls-webpki-roots enables the webpki-root-certs crate for root certificates when using native-tls.

Unstable

These features are unstable and might change in a minor version.

rustls-no-provider Enables rustls, but does not enable webpki and any [CryptoProvider] such as ring. Root certs and providers other than the default (currently ring) are never picked up from feature flags alone. They must be configured on the agent.
native-tls-no-default Enables native-tls, but does not enable webpki. Root certs are never picked up from feature flags alone. They must be configured on the agent.
vendored compiles and statically links to a copy of non-Rust vendors (e.g. OpenSSL from native-tls)

TLS (https)

rustls

By default, ureq uses [rustls crate] with the ring cryptographic provider. As of Sep 2024, the ring provider has a higher chance of compiling successfully. If the user installs another process [default provider], that choice is respected.

ureq does not guarantee to default to ring indefinitely. rustls as a feature flag will always work, but the specific crypto backend might change in a minor version.

// This uses rustls
ureq::get("https://www.google.com/").call().unwrap();

rustls without ring

ureq never changes TLS backend from feature flags alone. It is possible to compile ureq without ring, but it requires specific feature flags and configuring the [Agent].

Since rustls is not semver 1.x, this requires non-semver-guaranteed API. I.e. ureq might change this behavior without a major version bump.

Read more at [TlsConfigBuilder::unversioned_rustls_crypto_provider][crate::tls::TlsConfigBuilder::unversioned_rustls_crypto_provider].

native-tls

As an alternative, ureq ships with [native-tls] as a TLS provider. This must be enabled using the native-tls feature. Due to the risk of diamond dependencies accidentally switching on an unwanted TLS implementation, native-tls is never picked up as a default or used by the crate level convenience calls (ureq::get etc) – it must be configured on the agent.

use ureq::config::Config;
use ureq::tls::{TlsConfig, TlsProvider};

let mut config = Config::builder()
    .tls_config(
        TlsConfig::builder()
            // requires the native-tls feature
            .provider(TlsProvider::NativeTls)
            .build()
    )
    .build();

let agent = config.new_agent();

agent.get("https://www.google.com/").call().unwrap();

Root certificates

webpki-roots

By default, ureq uses Mozilla's root certificates via the [webpki-roots] crate. This is a static bundle of root certificates that do not update automatically. It also circumvents whatever root certificates are installed on the host running ureq, which might be a good or a bad thing depending on your perspective. There is also no mechanism for [SCT], [CRL]s or other revocations. To maintain a "fresh" list of root certs, you need to bump the ureq dependency from time to time.

The main reason for chosing this as the default is to minimize the number of dependencies. More details about this decision can be found at [PR 818].

If your use case for ureq is talking to a limited number of servers with high trust, the default setting is likely sufficient. If you use ureq with a high number of servers, or servers you don't trust, we recommend using the platform verifier (see below).

platform-verifier

The [rustls-platform-verifier] crate provides access to natively checking the certificate via your OS. To use this verifier, you need to enable it using feature flag platform-verifier as well as configure an agent to use it.

use ureq::Agent;
use ureq::tls::{TlsConfig, RootCerts};

let agent = Agent::config_builder()
    .tls_config(
        TlsConfig::builder()
            .root_certs(RootCerts::PlatformVerifier)
            .build()
    )
    .build()
    .new_agent();

let response = agent.get("https://httpbin.org/get").call()?;

Setting RootCerts::PlatformVerifier together with TlsProvider::NativeTls means also native-tls will use the OS roots instead of [webpki-roots] crate. Whether that results in a config that has CRLs and revocations is up to whatever native-tls links to.

JSON

By enabling the json feature, the library supports serde json.

This is disabled by default.

[request.send_json()] send body as json.
[body.read_json()] transform response to json.

Sending body data

HTTP/1.1 has two ways of transfering body data. Either of a known size with the Content-Length HTTP header, or unknown size with the Transfer-Encoding: chunked header. ureq supports both and will use the appropriate method depending on

Ureq

Install / Use

README

ureq

Usage

JSON

Error handling

Features

Unstable

TLS (https)

rustls

rustls without ring

native-tls

Root certificates

webpki-roots

platform-verifier

JSON

Sending body data