Configuration

Where settings come from at build time, install time, and runtime.

Build-time configuration

Autotools

./configure --help

Selected flags:

Flag	Effect
--with-openssl[=PATH]	Link against OpenSSL (or LibreSSL/BoringSSL/AWS-LC/quictls)
--with-gnutls[=PATH]	GnuTLS
--with-mbedtls[=PATH]	mbedTLS
--with-wolfssl[=PATH]	wolfSSL
--with-rustls[=PATH]	Rustls
--with-secure-transport	Apple SecureTransport (legacy, removed in 2025)
--with-schannel	Windows Schannel
--with-libssh2[=PATH] / --with-libssh[=PATH]	SSH backend
--with-nghttp2[=PATH]	HTTP/2
--with-ngtcp2 + --with-nghttp3	HTTP/3
--with-quiche	HTTP/3 via quiche
--with-c-ares	Async DNS via c-ares
--enable-threaded-resolver	Async DNS via thread pool
--without-ssl	Build without TLS at all
--enable-debug / --enable-curldebug	Memory tracking, asserts, sanitiser-friendly
--disable-<protocol> (e.g. --disable-ftp)	Compile out a protocol
--enable-ipv6 / --disable-ipv6	IPv6 support
--enable-cookies / --disable-cookies	Cookie engine
--enable-symbol-hiding	Hide private symbols (default on most platforms)
--with-libpsl	Public Suffix List support for cookies
--with-libidn2	International Domain Names
--with-zlib / --with-brotli / --with-zstd	Content encoding backends

CMake

cmake -B bld -DCURL_USE_OPENSSL=ON -DCURL_USE_LIBSSH2=ON

CMake variables follow the pattern CURL_USE_<LIB>=ON|OFF and CURL_DISABLE_<FEATURE>=ON|OFF. The full set is in CMakeLists.txt (~92 KB). Required for Windows.

Compile-time toggles

The macros in lib/curl_setup.h control what gets compiled into libcurl. These are usually set by the build system but can be set manually for embedded builds:

Macro	Disables
CURL_DISABLE_HTTP	HTTP and HTTPS
CURL_DISABLE_FTP	FTP and FTPS
CURL_DISABLE_TELNET	TELNET
CURL_DISABLE_LDAP	LDAP and LDAPS
CURL_DISABLE_TFTP	TFTP
CURL_DISABLE_DICT	DICT
CURL_DISABLE_FILE	FILE://
CURL_DISABLE_GOPHER	GOPHER and GOPHERS
CURL_DISABLE_IMAP	IMAP and IMAPS
CURL_DISABLE_POP3	POP3 and POP3S
CURL_DISABLE_SMTP	SMTP and SMTPS
CURL_DISABLE_RTSP	RTSP
CURL_DISABLE_MQTT	MQTT
CURL_DISABLE_WEBSOCKETS	WebSockets
CURL_DISABLE_NETRC	~/.netrc parsing
CURL_DISABLE_COOKIES	Cookie engine
CURL_DISABLE_HSTS	HSTS cache
CURL_DISABLE_ALTSVC	Alt-Svc cache
CURL_DISABLE_VERBOSE_STRINGS	Strip verbose error strings
CURL_DISABLE_DOH	DNS-over-HTTPS
CURL_DISABLE_GETOPTIONS	curl_easy_option_*
CURL_DISABLE_HEADERS_API	curl_easy_header

The full list is in lib/curl_setup.h and reflected in docs/CURL-DISABLE.md.

Runtime configuration

Configuration files

File	Read by	Format
~/.curlrc	the curl tool	One option per line, same syntax as -K config
${CURL_HOME}/.curlrc (override)	the curl tool	Same
~/.netrc	libcurl (lib/netrc.c) when CURLOPT_NETRC is on	machine / login / password blocks
Cookie jar	CURLOPT_COOKIEFILE/COOKIEJAR	Netscape cookie file format
HSTS file	CURLOPT_HSTS	Plain-text host-per-line
Alt-Svc file	CURLOPT_ALTSVC	Plain-text host-per-line
CA bundle	CURLOPT_CAINFO / --cacert	PEM-encoded list of trust anchors

Environment variables

Variable	Meaning
http_proxy	Default proxy for HTTP
https_proxy	Default proxy for HTTPS
ftp_proxy	Default proxy for FTP
all_proxy	Default proxy for any scheme
no_proxy	Comma-separated list of hosts to bypass the proxy
CURL_CA_BUNDLE	Path to a CA bundle (overrides defaults)
CURL_HOME	Override $HOME for ~/.curlrc lookup
CURL_SSL_BACKEND	When multiSSL is built, choose backend at runtime
SSLKEYLOGFILE	Where TLS pre-master secrets are logged for Wireshark
CURL_DEBUG	Debug-build only: free-form debug toggles
CURL_TRC_FT_*	Per-component trace toggles (debug builds)
CURL_MEMDEBUG	Debug-build memory log file
CURL_TIMEOUT_MULT	Multiplier for timeouts in tests
HOME	Standard POSIX (used to find ~/.curlrc, ~/.netrc)

libcurl programmatic options

Every CURLOPT_* option is documented at https://curl.se/libcurl/c/. The exhaustive list is in include/curl/curl.h and the per-option behaviour in docs/libcurl/opts/CURLOPT_*.md.

Defaults

Default	Where it lives
Connection timeout	CURLOPT_CONNECTTIMEOUT default 300 seconds
Total transfer timeout	None (CURLOPT_TIMEOUT 0 = no timeout)
DNS cache TTL	CURLOPT_DNS_CACHE_TIMEOUT default 60 seconds
Max connection cache	CURLMOPT_MAXCONNECTS default 0 (unlimited)
Followed redirects	CURLOPT_FOLLOWLOCATION default 0 (off)
Default protocols allowed for redirect	HTTP, HTTPS, FTP, FTPS
Verify peer	CURLOPT_SSL_VERIFYPEER default 1 (on)
Verify hostname	CURLOPT_SSL_VERIFYHOST default 2 (verify)
Default user-agent	None — applications must set it (the curl tool sets curl/<version>)