Artifactspublic-v0

curl

master
ply4 git calls33 ms298 KiB3 cachedprotocol v2
682 lines26 KiBRaw

How to install curl and libcurl

Installing Binary Packages

Lots of people download binary distributions of curl and libcurl. This document does not describe how to install curl or libcurl using such a binary package. This document describes how to compile, build and install curl and libcurl from source code.

Verifying the source archive

Before unpacking a downloaded release tarball, verify its GPG signature against the published key. The signature (.asc) is available next to the tarball on https://curl.se/download.html.

gpg --verify curl-X.Y.Z.tar.gz.asc curl-X.Y.Z.tar.gz

You can find the signing key fingerprint, and reproducible-release verification, documented in docs/VERIFY.md.

This protects against tampered mirrors and CDNs, MITM proxies, but not against a compromised maintainer signing key.

Building from source

You can use autotools or CMake to build curl from source. They both work well and have close to feature parity.

autotools' advantages are wide portability and the Unix philosophy, while CMake typically has faster configuration and build times, and supports MSVC.

Option defaults and dependency detection details may differ.

With both build tools, some features require Perl, and the pytest test suite requires Python.

You can find live examples for both tools and build cases in curl's CI scripts: .github/workflows/*.yml and appveyor.* (in the Git repository). For CMake-specific instructions, see INSTALL-CMAKE.md.

Building using vcpkg

You can download and install curl and libcurl using the vcpkg dependency manager:

git clone --depth 1 https://github.com/Microsoft/vcpkg
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install curl[tool]

The curl port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

Building from git

If you get your code off a git repository instead of a release tarball, see the GIT-INFO.md file in the root directory for specific instructions on how to proceed.

Unix

A normal Unix installation is made in three or four steps (after you have unpacked the source archive):

./configure --with-openssl [--with-gnutls --with-wolfssl]
make
make test (optional)
make install

(Adjust the configure line accordingly to use the TLS library you want.)

By default curl builds with libpsl (Public Suffix List) support. If libpsl is not available on your system, install it or disable it with --without-libpsl.

You probably need to be root when doing the last command.

Get a full listing of all available configure options by invoking it like:

./configure --help

If you want to install curl in a different file hierarchy than /usr/local, specify that when running configure:

./configure --prefix=/path/to/curl/tree

If you have write permission in that directory, you can do 'make install' without being root. An example of this would be to make a local install in your own home directory:

./configure --prefix="$HOME"
make
make install

The configure script requires you to select a TLS backend explicitly unless you disable TLS with --without-ssl. If you have OpenSSL installed in the default search path for your compiler/linker, you can run configure like:

./configure --with-openssl

If you have OpenSSL installed somewhere else (for example, /opt/OpenSSL) and you have pkg-config installed, set the pkg-config path first, like this:

env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-openssl

Without pkg-config installed, use this:

./configure --with-openssl=/opt/OpenSSL

If you insist on forcing a build without SSL support, you can run configure like this:

./configure --without-ssl

If you have OpenSSL installed, but with the libraries in one place and the header files somewhere else, you have to set the LDFLAGS and CPPFLAGS environment variables prior to running configure. Something like this should work:

CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure --with-openssl

If you have shared SSL libs installed in a directory where your runtime linker does not find them (which usually causes configure failures), you can provide this option to gcc to set a hard-coded path to the runtime linker:

LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-openssl

Static builds

To force a static library compile, disable the shared library creation by running configure like:

./configure --disable-shared

The configure script is primarily done to work with shared/dynamic third party dependencies. When linking with shared libraries, the library loader handles the dependency "chain" automatically - on all modern systems.

If you instead link with a static library, you need to provide all the dependency libraries already at the link command line.

Figuring out all the dependency libraries for a given library is hard, as it might involve figuring out the dependencies of the dependencies and they vary between platforms and change between versions.

When using static dependencies, the build scripts mostly assume that you, the user, provide all the necessary additional dependency libraries as additional arguments in the build. With configure, by setting LIBS or LDFLAGS on the command line.

Building statically is not for the faint of heart.

Debug

If you are a curl developer and use gcc, you might want to enable curl debug features (for developing curl) with the --enable-debug option.

curl can be built to use a whole range of libraries to provide various useful services, and configure tries to auto-detect a decent default. If you want to alter it, you can select how to deal with each individual library.

To debug the build itself, you can set the environment variable CURL_TRACE_PKG_CONFIG to a non-empty value to enable detailed trace information and verbose errors from pkg-config module detection invocations.

Select TLS backend

These are the options available to select the TLS backend to use.

  • AmiSSL: --with-amissl
  • GnuTLS: --with-gnutls.
  • mbedTLS: --with-mbedtls
  • OpenSSL: --with-openssl (also for AWS-LC, BoringSSL, LibreSSL, and quictls)
  • Rustls: --with-rustls
  • Schannel: --with-schannel
  • wolfSSL: --with-wolfssl

You can build curl with multiple TLS backends at your choice, but some TLS backends cannot coexist: if you build with OpenSSL (or fork), you cannot add another OpenSSL fork because they have conflicting identical symbol names. wolfSSL 5.7.6+, depending on its build options, can coexist with OpenSSL (and forks).

When you build with multiple TLS backends, you can select the active one at runtime when curl starts up.

Selecting TLS Trust Anchors Defaults

Verifying a server certificate establishes a chain of trust that needs to start somewhere. Those "root" certificates make the set of Trust Anchors.

While the build system tries to find good defaults on the platform you use, you may specify these explicitly. The following options are provided:

  • --with-ca-bundle=FILE: the file that libcurl loads default root certificates from.
  • --with-ca-path=DIRECTORY: a directory in which root certificates files are found.
  • --with-ca-embed=FILE: a file read at build time and added to libcurl.
  • --with-ca-fallback: an OpenSSL specific option for delegating default trust anchor selection to what OpenSSL thinks is best, if there are no other certificates configured by the application.
  • --with-apple-sectrust: use the system "SecTrust" service on Apple operating systems for verification. (Added in 8.17.0)
  • --enable-ca-native: use the Windows system CA store for verification. (Added in 8.19.0)
  • --disable-ca-search: prevent the curl tool searching for a CA bundle (curl-ca-bundle.crt) in its own directory and in PATH on Windows. To improve security by not picking up potentially outdated or crafted CA roots. (Added in 8.11.0)
  • --enable-ca-search-safe: restrict the curl tool searching for a CA bundle to its own directory. A safe option if the curl tool resides in a protected directory with the CA bundle kept in the same directory. (Added in 8.11.0)

MultiSSL and HTTP/3

HTTP/3 needs QUIC and QUIC needs TLS. Building libcurl with HTTP/3 and QUIC support is not compatible with the MultiSSL feature: they are mutually exclusive. If you need MultiSSL in your build, you cannot have HTTP/3 support and vice versa.

libcurl can only use a single TLS library with QUIC and that same TLS library needs to be used for the other TLS using protocols.

Configure finding libs in wrong directory

When the configure script checks for third-party libraries, it adds those directories to the LDFLAGS variable and then tries linking to see if it works. When successful, the found directory is kept in the LDFLAGS variable when the script continues to execute and do more tests and possibly check for more libraries.

This can make subsequent checks for libraries wrongly detect another installation in a directory that was previously added to LDFLAGS by another library check.

Windows

Building for Windows Vista/Server 2008 is required as a minimum.

You can build curl with:

  • Microsoft Visual Studio 2010 10.0 or greater (_MSC_VER >= 1600)
  • mingw-w64 3.0 or greater (__MINGW64_VERSION_MAJOR >= 3)

Building Windows DLLs and C runtime (CRT) linkage issues

As a general rule, building a DLL with static CRT linkage is highly discouraged, and intermixing CRTs in the same app is something to avoid at any cost.

Reading and comprehending Microsoft Knowledge Base articles KB94248 and KB140584 is a must for any Windows developer. Especially important is full understanding if you are not going to follow the advice given above.

If your app is misbehaving in some strange way, or it is suffering from memory corruption, before asking for further help, please try first to rebuild every single library your app uses as well as your app using the debug multi-threaded dynamic C runtime.

If you get linkage errors read section 5.7 of the FAQ document.

Cygwin

Almost identical to the Unix installation. Download the curl source code, then essentially run the configure script in the curl source tree root with sh configure, then run make.

To expand on building with Cygwin first ensure it is in your path, and there are no conflicting tools (i.e. Chocolatey with sed package). If so move Cygwin ahead of any items in your path that would conflict with Cygwin commands, making sure you have the sh executable in /bin/ or you see the configure fail toward the end.

Download the setup installer from Cygwin to begin. Additional Cygwin packages are needed for the install. For more on installing packages visit Cygwin Setup.

Either run setup-x86_64.exe, then search and select packages individually, or try:

setup-x86_64.exe --no-admin -q -I -P binutils,gcc-core,libpsl-devel,libtool,perl,make

Expand the below details to show the list of required packages for a successful Cygwin install:

<details> <summary>Package List</summary>

binutils
gcc-core
libpsl-devel
libtool
perl
make

</details>

Once all the packages have been installed, begin the process of installing curl from the source code:

<details> <summary>configure_options</summary>

--with-gnutls
--with-mbedtls
--with-openssl (also works for OpenSSL forks)
--with-rustls
--with-wolfssl
--without-ssl

</details>

  1. sh configure <configure_options>
  2. make

[!Note] If an error occurs during the installation, then try:

  • Using cmake to configure and/or build
  • Using ninja to build (much faster)
  • Reinstalling the required Cygwin packages from the list above without passing -I to setup-x86_64
  • Temporarily moving Cygwin to the top of your path
  • Installing all of the Cygwin build packages using setup-x86_64 --build-depends curl

MS-DOS

You can use either autotools or CMake:

sh
./configure \
  CC=/path/to/djgpp/bin/i586-pc-msdosdjgpp-gcc \
  AR=/path/to/djgpp/bin/i586-pc-msdosdjgpp-ar \
  RANLIB=/path/to/djgpp/bin/i586-pc-msdosdjgpp-ranlib \
  WATT_ROOT=/path/to/djgpp/net/watt \
  --host=i586-pc-msdosdjgpp \
  --with-openssl=/path/to/djgpp \
  --with-zlib=/path/to/djgpp \
  --without-libpsl \
  --disable-shared
sh
cmake . \
  -DCMAKE_SYSTEM_NAME=DOS \
  -DCMAKE_C_COMPILER_TARGET=i586-pc-msdosdjgpp \
  -DCMAKE_C_COMPILER=/path/to/djgpp/bin/i586-pc-msdosdjgpp-gcc \
  -DWATT_ROOT=/path/to/djgpp/net/watt \
  -DOPENSSL_INCLUDE_DIR=/path/to/djgpp/include \
  -DOPENSSL_SSL_LIBRARY=/path/to/djgpp/lib/libssl.a \
  -DOPENSSL_CRYPTO_LIBRARY=/path/to/djgpp/lib/libcrypto.a \
  -DZLIB_INCLUDE_DIR=/path/to/djgpp/include \
  -DZLIB_LIBRARY=/path/to/djgpp/lib/libz.a \
  -DCURL_USE_LIBPSL=OFF

Notes:

  • Requires DJGPP 2.04 or greater.

  • Compile Watt-32 (and OpenSSL) with the same version of DJGPP. Otherwise things go wrong because things like FS-extensions and errno values have been changed between releases.

AmigaOS

You can use either autotools or CMake:

sh
./configure \
  CC=/opt/amiga/bin/m68k-amigaos-gcc \
  AR=/opt/amiga/bin/m68k-amigaos-ar \
  RANLIB=/opt/amiga/bin/m68k-amigaos-ranlib \
  --host=m68k-amigaos \
  --with-amissl \
  CFLAGS='-O0 -msoft-float -mcrt=clib2' \
  CPPFLAGS=-I/path/to/AmiSSL/Developer/include \
  LDFLAGS=-L/path/to/AmiSSL/Developer/lib/AmigaOS3 \
  LIBS='-lnet -lm -latomic' \
  --without-libpsl \
  --disable-shared
sh
cmake . \
  -DAMIGA=1 \
  -DCMAKE_SYSTEM_NAME=Generic \
  -DCMAKE_C_COMPILER_TARGET=m68k-unknown-amigaos \
  -DCMAKE_C_COMPILER=/opt/amiga/bin/m68k-amigaos-gcc \
  -DCMAKE_C_FLAGS='-O0 -msoft-float -mcrt=clib2' \
  -DAMISSL_INCLUDE_DIR=/path/to/AmiSSL/Developer/include \
  -DAMISSL_STUBS_LIBRARY=/path/to/AmiSSL/Developer/lib/AmigaOS3/libamisslstubs.a \
  -DAMISSL_AUTO_LIBRARY=/path/to/AmiSSL/Developer/lib/AmigaOS3/libamisslauto.a \
  -DCURL_USE_LIBPSL=OFF

Important static libcurl usage note

When building an application that uses the static libcurl library on Windows, you must add -DCURL_STATICLIB to your CFLAGS. Otherwise the linker looks for dynamic import symbols.

Legacy Windows and SSL

Schannel (from Windows SSPI), is the native SSL library in Windows. Schannel in earlier Windows versions may be unable to connect to servers that no longer support the legacy handshakes and algorithms used by those versions. If you are using curl in such Windows versions you should choose another SSL backend such as OpenSSL.

Android

When building curl for Android you can either use CMake or configure.

Before you can build curl for Android, you need to install the Android NDK first. This can be done using the SDK Manager that is part of Android Studio. Once you have installed the Android NDK, you need to figure out where it has been installed and then set up some environment variables before launching the build.

Examples to compile for aarch64 and API level 29:

with CMake, where ANDROID_NDK_HOME points into your NDK:

sh
cmake . \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-29 \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_HOME"/build/cmake/android.toolchain.cmake \
  -DCURL_ENABLE_SSL=OFF \
  -DCURL_USE_LIBPSL=OFF

with configure, on macOS:

sh
export ANDROID_NDK_HOME="$HOME"/Library/Android/sdk/ndk/25.1.8937393  # Point into your NDK
# Same tag for Apple Silicon. Other OS values here:
#   https://developer.android.com/ndk/guides/other_build_systems#overview
export HOST_TAG=darwin-x86_64
export TOOLCHAIN="$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/$HOST_TAG
export AR="$TOOLCHAIN"/bin/llvm-ar
export AS="$TOOLCHAIN"/bin/llvm-as
export CC="$TOOLCHAIN"/bin/aarch64-linux-android29-clang
export CXX="$TOOLCHAIN"/bin/aarch64-linux-android29-clang++
export LD="$TOOLCHAIN"/bin/ld
export RANLIB="$TOOLCHAIN"/bin/llvm-ranlib
export STRIP="$TOOLCHAIN"/bin/llvm-strip

When building on Linux or targeting other API levels or architectures, you need to adjust those variables accordingly. After that you can build curl like this:

./configure --host aarch64-linux-android --with-pic --disable-shared

Note that this does not give you SSL/TLS support. If you need SSL/TLS, you have to build curl with an SSL/TLS library, e.g. OpenSSL, because it is impossible for curl to access Android's native SSL/TLS layer. To build curl for Android using OpenSSL, follow the OpenSSL build instructions and then install libssl.a and libcrypto.a to $TOOLCHAIN/sysroot/usr/lib and copy include/openssl to $TOOLCHAIN/sysroot/usr/include. Now you can build curl for Android using OpenSSL like this:

sh
# For AWS-LC/BoringSSL/OpenSSL. In general, you need to the SSL/TLS layer's
# transitive dependencies if you are linking statically.
export LIBS='-lssl -lcrypto -lc++'
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN"/sysroot/usr

IBM i

For IBM i (formerly OS/400), you can use curl in two different ways:

  • Natively, running in the ILE. The obvious use is being able to call curl from ILE C or RPG applications.
  • You need to build this from source. See projects/OS400/README for the ILE specific build instructions.
  • In the PASE environment, which runs AIX programs. curl is built as it would be on AIX.
  • IBM provides builds of curl in their Yum repository for PASE software.
  • To build from source, follow the Unix instructions.

There are some additional limitations and quirks with curl on this platform; they affect both environments.

Multi-threading notes

By default, jobs in IBM i does not start with threading enabled. (Exceptions include interactive PASE sessions started by QP2TERM or SSH.) If you use curl in an environment without threading when options like asynchronous DNS were enabled, you get messages like:

getaddrinfo() thread failed to start

Do not panic. curl and your program are not broken. You can fix this by:

  • Set the environment variable QIBM_MULTI_THREADED to Y before starting your program. This can be done at whatever scope you feel is appropriate.
  • Alternatively, start the job with the ALWMLTTHD parameter set to *YES.

Cross compile

Download and unpack the curl package.

cd to the new directory. (e.g. cd curl-7.12.3)

Set environment variables to point to the cross-compile toolchain and call configure with any options you need. Be sure and specify the --host and --build parameters at configuration time. The following script is an example of cross-compiling for the IBM 405GP PowerPC processor using the toolchain on Linux.

sh
export PATH="$PATH":/opt/hardhat/devkit/ppc/405/bin
export CPPFLAGS=-I/opt/hardhat/devkit/ppc/405/target/usr/include
export AR=ppc_405-ar
export AS=ppc_405-as
export LD=ppc_405-ld
export RANLIB=ppc_405-ranlib
export CC=ppc_405-gcc
export NM=ppc_405-nm

./configure \
  --target=powerpc-hardhat-linux \
  --host=powerpc-hardhat-linux \
  --build=i586-pc-linux-gnu \
  --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
  --exec-prefix=/usr/local

The --prefix parameter specifies where curl gets installed. If configure completes, do make and make install as usual.

In some cases, you may be able to simplify the above commands to as little as:

./configure --host=ARCH-OS

REDUCING SIZE

There are a number of configure options that you can use to reduce the size of libcurl for embedded applications where binary size is an important factor. First, be sure to set the CFLAGS variable when configuring with any relevant compiler optimization flags to reduce the size of the binary. For gcc, this would mean at minimum the -Os option, and others like the following that may be relevant in some environments: -march=X, -mthumb, -m32, -mdynamic-no-pic, -flto, -fdata-sections, -ffunction-sections, -fno-unwind-tables, -fno-asynchronous-unwind-tables, -fno-record-gcc-switches, -fsection-anchors, -fno-plt, -Wl,--gc-sections, -Wl,-dead_strip (Apple), -Wl,-Bsymbolic, -Wl,-s

For example, this is how to combine a few of these options:

./configure CC=gcc CFLAGS='-Os -ffunction-sections' LDFLAGS='-Wl,--gc-sections' ...

Note that newer compilers often produce smaller code than older versions due to improved optimization.

Be sure to specify as many --disable- and --without- flags on the configure command-line as you can to disable all the libcurl features that you know your application is not going to need. Besides specifying the --disable-PROTOCOL flags for all the types of URLs your application do not use, here are some other flags that can reduce the size of the library by disabling support for some features (run ./configure --help to see them all):

  • --disable-aws (cryptographic authentication)
  • --disable-basic-auth (cryptographic authentication)
  • --disable-bearer-auth (cryptographic authentication)
  • --disable-digest-auth (cryptographic authentication)
  • --disable-http-auth (all HTTP authentication)
  • --disable-kerberos-auth (cryptographic authentication)
  • --disable-negotiate-auth (cryptographic authentication)
  • --disable-alt-svc (HTTP Alt-Svc)
  • --disable-ares (the C-ARES DNS library)
  • --disable-cookies (HTTP cookies)
  • --disable-dateparse (date parsing for time conditionals)
  • --disable-dnsshuffle (internal server load spreading)
  • --disable-doh (DNS-over-HTTP)
  • --disable-form-api (POST form API)
  • --disable-get-easy-options (lookup easy options at runtime)
  • --disable-headers-api (API to access headers)
  • --disable-hsts (HTTP Strict Transport Security)
  • --disable-ipv6 (IPv6)
  • --disable-libcurl-option (--libcurl C code generation support)
  • --disable-manual (--manual built-in documentation)
  • --disable-mime (MIME API)
  • --disable-netrc (.netrc file)
  • --disable-progress-meter (graphical progress meter in library)
  • --disable-proxy (HTTP and SOCKS proxies)
  • --disable-socketpair (socketpair for asynchronous name resolving)
  • --disable-threaded-resolver (threaded name resolver)
  • --disable-unix-sockets (Unix sockets)
  • --disable-verbose (eliminates debugging strings and error code strings)
  • --disable-versioned-symbols (versioned symbols)
  • --enable-symbol-hiding (eliminates unneeded symbols in the shared library)
  • --without-brotli (Brotli on-the-fly decompression)
  • --without-libpsl (Public Suffix List in cookies)
  • --without-nghttp2 (HTTP/2 using nghttp2)
  • --without-ngtcp2 (HTTP/2 using ngtcp2)
  • --without-zstd (Zstd on-the-fly decompression)
  • --without-libidn2 (internationalized domain names)
  • --without-ssl (SSL/TLS)
  • --without-zlib (gzip/deflate on-the-fly decompression)

You can find the CMake-equivalents in INSTALL-CMAKE.md.

Be sure also to strip debugging symbols from your binaries after compiling using strip or an option like -s. If space is tight, you may be able to gain a few bytes by removing unneeded sections of the shared library using the -R option to objcopy (e.g. the .comment section).

Using these techniques it is possible to create a basic HTTP-only libcurl shared library for i386 Linux platforms that is only 137 KiB in size (as of libcurl version 8.13.0, using gcc 14.2.0).

You may find that statically linking libcurl to your application results in a lower total size than dynamically linking.

The curl test harness can detect the use of some, but not all, of the --disable statements suggested above. Use of these can cause tests relying on those features to fail. The test harness can be manually forced to skip the relevant tests by specifying certain key words on the runtests.pl command line. Following is a list of appropriate key words for those configure options that are not automatically detected:

  • --disable-cookies !cookies
  • --disable-dateparse !RETRY-AFTER !CURLOPT_TIMECONDITION !CURLINFO_FILETIME !If-Modified-Since !curl_getdate !-z
  • --disable-libcurl-option !--libcurl
  • --disable-verbose !verbose\ logs

Ports

This is a probably incomplete list of known CPU architectures and operating systems that curl has been compiled for. If you know a system curl compiles and runs on, that is not listed, please let us know.

108 Operating Systems

AIX, AmigaOS, Android, ArcaOS, Aros, Atari FreeMiNT, Azure Sphere, BeOS,
Blackberry 10, Blackberry Tablet OS, Cell OS, Cesium, CheriBSD, Chrome OS,
Cisco IOS, DG/UX, DR DOS, Dragonfly BSD, eCOS, FreeBSD, FreeDOS, FreeRTOS,
Fuchsia, Garmin OS, Genode, Haiku, HardenedBSD, HP-UX, Hurd, IBM I,
illumos, Integrity, iOS, ipadOS, IRIX, KasperskyOS, Linux, Lua RTOS,
Mac OS 9, macOS, Maemo, Mbed, Meego, Micrium, MINIX, Minoca, Moblin,
MorphOS, MPE/iX, MS-DOS, NCR MP-RAS, NetBSD, Netware, NextStep,
Nintendo 3DS, Nintendo Switch, NonStop OS, NuttX, OpenBSD, OpenStep,
Orbis OS, OS/2, OS21, PikeOS, Plan 9, PlayStation Portable, QNX, Qubes OS,
ReactOS, Redox, RISC OS, ROS, RTEMS, Sailfish OS, SCO Unix, Serenity,
SINIX-Z, SkyOS, SmartOS, Solaris, Sortix, SunOS, Syllable OS, Symbian,
Tizen, TPF, Tru64, tvOS, ucLinux, Ultrix, UNICOS, UnixWare, visionOS, VMS,
vxWorks, watchOS, Wear OS, WebOS, Wii System Software, Wii U, Windows,
Xbox System, Xenix, z/OS, z/TPF, z/VM, z/VSE, Zephyr

28 CPU Architectures

Alpha, ARC, ARM, AVR32, C-SKY, CompactRISC, Elbrus, ETRAX, HP-PA, Itanium,
LoongArch, m68k, m88k, MicroBlaze, MIPS, Nios, OpenRISC, POWER, PowerPC,
RISC-V, s390, SH4, SPARC, Tilera, VAX, x86, Xtensa, z/arch
1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# How to install curl and libcurl
9## Installing Binary Packages
11Lots of people download binary distributions of curl and libcurl. This
12document does not describe how to install curl or libcurl using such a binary
13package. This document describes how to compile, build and install curl and
14libcurl from [source code](https://curl.se/download.html).
16## Verifying the source archive
18Before unpacking a downloaded release tarball, verify its GPG signature
19against the published key. The signature (`.asc`) is available next to
20the tarball on https://curl.se/download.html.
22 gpg --verify curl-X.Y.Z.tar.gz.asc curl-X.Y.Z.tar.gz
24You can find the signing key fingerprint, and reproducible-release
25verification, documented in
26[docs/VERIFY.md](https://github.com/curl/curl/blob/master/docs/VERIFY.md).
28This protects against tampered mirrors and CDNs, MITM proxies, but not against
29a compromised maintainer signing key.
31## Building from source
33You can use autotools or CMake to build curl from source. They both work well
34and have close to feature parity.
36autotools' advantages are wide portability and the Unix philosophy, while
37CMake typically has faster configuration and build times, and supports MSVC.
39Option defaults and dependency detection details may differ.
41With both build tools, some features require Perl, and the pytest test suite
42requires Python.
44You can find live examples for both tools and build cases in curl's CI
45scripts: `.github/workflows/*.yml` and `appveyor.*` (in the Git repository).
46For CMake-specific instructions, see
47[INSTALL-CMAKE.md](https://github.com/curl/curl/blob/master/docs/INSTALL-CMAKE.md).
49## Building using vcpkg
51You can download and install curl and libcurl using
52the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
54 git clone --depth 1 https://github.com/Microsoft/vcpkg
55 cd vcpkg
56 ./bootstrap-vcpkg.sh
57 ./vcpkg integrate install
58 vcpkg install curl[tool]
60The curl port in vcpkg is kept up to date by Microsoft team members and
61community contributors. If the version is out of date, please [create an issue
62or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
64## Building from git
66If you get your code off a git repository instead of a release tarball, see
67the [GIT-INFO.md](https://github.com/curl/curl/blob/master/GIT-INFO.md) file in
68the root directory for specific instructions on how to proceed.
70# Unix
72A normal Unix installation is made in three or four steps (after you have
73unpacked the source archive):
75 ./configure --with-openssl [--with-gnutls --with-wolfssl]
76 make
77 make test (optional)
78 make install
80(Adjust the configure line accordingly to use the TLS library you want.)
82By default curl builds with libpsl (Public Suffix List) support. If libpsl is
83not available on your system, install it or disable it with `--without-libpsl`.
85You probably need to be root when doing the last command.
87Get a full listing of all available configure options by invoking it like:
89 ./configure --help
91If you want to install curl in a different file hierarchy than `/usr/local`,
92specify that when running configure:
94 ./configure --prefix=/path/to/curl/tree
96If you have write permission in that directory, you can do 'make install'
97without being root. An example of this would be to make a local install in
98your own home directory:
100 ./configure --prefix="$HOME"
101 make
102 make install
104The configure script requires you to select a TLS backend explicitly unless
105you disable TLS with `--without-ssl`. If you have OpenSSL installed in the
106default search path for your compiler/linker, you can run configure like:
108 ./configure --with-openssl
110If you have OpenSSL installed somewhere else (for example, `/opt/OpenSSL`) and
111you have pkg-config installed, set the pkg-config path first, like this:
113 env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-openssl
115Without pkg-config installed, use this:
117 ./configure --with-openssl=/opt/OpenSSL
119If you insist on forcing a build without SSL support, you can run configure
120like this:
122 ./configure --without-ssl
124If you have OpenSSL installed, but with the libraries in one place and the
125header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
126environment variables prior to running configure. Something like this should
127work:
129 CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure --with-openssl
131If you have shared SSL libs installed in a directory where your runtime
132linker does not find them (which usually causes configure failures), you can
133provide this option to gcc to set a hard-coded path to the runtime linker:
135 LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-openssl
137## Static builds
139To force a static library compile, disable the shared library creation by
140running configure like:
142 ./configure --disable-shared
144The configure script is primarily done to work with shared/dynamic third party
145dependencies. When linking with shared libraries, the library loader handles
146the dependency "chain" automatically - on all modern systems.
148If you instead link with a static library, you need to provide all the
149dependency libraries already at the link command line.
151Figuring out all the dependency libraries for a given library is hard, as it
152might involve figuring out the dependencies of the dependencies and they vary
153between platforms and change between versions.
155When using static dependencies, the build scripts mostly assume that you, the
156user, provide all the necessary additional dependency libraries as additional
157arguments in the build. With configure, by setting `LIBS` or `LDFLAGS` on the
158command line.
160Building statically is not for the faint of heart.
162## Debug
164If you are a curl developer and use gcc, you might want to enable curl debug
165features (for developing curl) with the `--enable-debug` option.
167curl can be built to use a whole range of libraries to provide various useful
168services, and configure tries to auto-detect a decent default. If you want to
169alter it, you can select how to deal with each individual library.
171To debug the build itself, you can set the environment variable
172`CURL_TRACE_PKG_CONFIG` to a non-empty value to enable detailed trace
173information and verbose errors from `pkg-config` module detection invocations.
175## Select TLS backend
177These are the options available to select the TLS backend to use.
179- AmiSSL: `--with-amissl`
180- GnuTLS: `--with-gnutls`.
181- mbedTLS: `--with-mbedtls`
182- OpenSSL: `--with-openssl` (also for AWS-LC, BoringSSL, LibreSSL, and quictls)
183- Rustls: `--with-rustls`
184- Schannel: `--with-schannel`
185- wolfSSL: `--with-wolfssl`
187You can build curl with *multiple* TLS backends at your choice, but some TLS
188backends cannot coexist: if you build with OpenSSL (or fork), you cannot add
189another OpenSSL fork because they have conflicting identical symbol names.
190wolfSSL 5.7.6+, depending on its build options, can coexist with OpenSSL (and
191forks).
193When you build with multiple TLS backends, you can select the active one at
194runtime when curl starts up.
196### Selecting TLS Trust Anchors Defaults
198Verifying a server certificate establishes a chain of trust that needs to
199start somewhere. Those "root" certificates make the set of Trust Anchors.
201While the build system tries to find good defaults on the platform you
202use, you may specify these explicitly. The following options are provided:
204- `--with-ca-bundle=FILE`: the file that libcurl loads default root
205 certificates from.
206- `--with-ca-path=DIRECTORY`: a directory in which root certificates files
207 are found.
208- `--with-ca-embed=FILE`: a file read *at build time* and added to `libcurl`.
209- `--with-ca-fallback`: an OpenSSL specific option for delegating default
210 trust anchor selection to what OpenSSL thinks is best, *if* there are
211 no other certificates configured by the application.
212- `--with-apple-sectrust`: use the system "SecTrust" service on Apple
213 operating systems for verification. (Added in 8.17.0)
214- `--enable-ca-native`: use the Windows system CA store for verification.
215 (Added in 8.19.0)
216- `--disable-ca-search`: prevent the curl tool searching for a CA bundle
217 (`curl-ca-bundle.crt`) in its own directory and in PATH on Windows.
218 To improve security by not picking up potentially outdated or crafted
219 CA roots. (Added in 8.11.0)
220- `--enable-ca-search-safe`: restrict the curl tool searching for a CA bundle
221 to its own directory. A safe option if the curl tool resides in a protected
222 directory with the CA bundle kept in the same directory. (Added in 8.11.0)
224## MultiSSL and HTTP/3
226HTTP/3 needs QUIC and QUIC needs TLS. Building libcurl with HTTP/3 and QUIC
227support is not compatible with the MultiSSL feature: they are mutually
228exclusive. If you need MultiSSL in your build, you cannot have HTTP/3 support
229and vice versa.
231libcurl can only use a single TLS library with QUIC and that *same* TLS
232library needs to be used for the other TLS using protocols.
234## Configure finding libs in wrong directory
236When the configure script checks for third-party libraries, it adds those
237directories to the `LDFLAGS` variable and then tries linking to see if it
238works. When successful, the found directory is kept in the `LDFLAGS` variable
239when the script continues to execute and do more tests and possibly check for
240more libraries.
242This can make subsequent checks for libraries wrongly detect another
243installation in a directory that was previously added to `LDFLAGS` by another
244library check.
246# Windows
248Building for Windows Vista/Server 2008 is required as a minimum.
250You can build curl with:
252- Microsoft Visual Studio 2010 10.0 or greater (`_MSC_VER >= 1600`)
253- mingw-w64 3.0 or greater (`__MINGW64_VERSION_MAJOR >= 3`)
255## Building Windows DLLs and C runtime (CRT) linkage issues
257As a general rule, building a DLL with static CRT linkage is highly
258discouraged, and intermixing CRTs in the same app is something to avoid at
259any cost.
261Reading and comprehending Microsoft Knowledge Base articles KB94248 and
262KB140584 is a must for any Windows developer. Especially important is full
263understanding if you are not going to follow the advice given above.
265- [How To Use the C Runtime](https://learn.microsoft.com/troubleshoot/developer/visualstudio/cpp/libraries/use-c-run-time)
266- [Runtime Library Compiler Options](https://learn.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
267- [Potential Errors Passing CRT Objects
268 Across DLL Boundaries](https://learn.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
270If your app is misbehaving in some strange way, or it is suffering from memory
271corruption, before asking for further help, please try first to rebuild every
272single library your app uses as well as your app using the debug
273multi-threaded dynamic C runtime.
275If you get linkage errors read section 5.7 of the FAQ document.
277## Cygwin
279Almost identical to the Unix installation. Download the `curl` source code,
280then essentially run the configure script in the curl source tree root with
281`sh configure`, then run `make`.
283To expand on building with Cygwin first ensure it is in your path, and
284there are no conflicting tools (*i.e. Chocolatey with sed package*). If so
285move Cygwin ahead of any items in your path that would conflict with
286Cygwin commands, making sure you have the `sh` executable in `/bin/` or
287you see the configure fail toward the end.
289Download the setup installer from [Cygwin](https://cygwin.com/) to begin.
290Additional Cygwin packages are needed for the install. For more on
291installing packages visit
292[Cygwin Setup](https://cygwin.com/faq/faq.html#faq.setup.cli).
294Either run `setup-x86_64.exe`, then search and select packages individually,
295or try:
297 setup-x86_64.exe --no-admin -q -I -P binutils,gcc-core,libpsl-devel,libtool,perl,make
299Expand the below details to show the list of required packages for a
300successful Cygwin install:
302<details>
303 <summary>Package List</summary>
305```
306binutils
307gcc-core
308libpsl-devel
309libtool
310perl
311make
312```
314</details>
316Once all the packages have been installed, begin the process of installing
317curl from the source code:
319<details>
320 <summary>configure_options</summary>
322```
323--with-gnutls
324--with-mbedtls
325--with-openssl (also works for OpenSSL forks)
326--with-rustls
327--with-wolfssl
328--without-ssl
329```
331</details>
3331. `sh configure <configure_options>`
3342. `make`
336> [!Note]
337> If an error occurs during the installation, then try:
339- Using `cmake` to configure and/or build
340- Using `ninja` to build (much faster)
341- Reinstalling the required Cygwin packages from the list above without
342 passing `-I` to `setup-x86_64`
343- Temporarily moving Cygwin to the top of your path
344- Installing all of the Cygwin build packages using
345 `setup-x86_64 --build-depends curl`
347## MS-DOS
349You can use either autotools or CMake:
351```sh
352./configure \
353 CC=/path/to/djgpp/bin/i586-pc-msdosdjgpp-gcc \
354 AR=/path/to/djgpp/bin/i586-pc-msdosdjgpp-ar \
355 RANLIB=/path/to/djgpp/bin/i586-pc-msdosdjgpp-ranlib \
356 WATT_ROOT=/path/to/djgpp/net/watt \
357 --host=i586-pc-msdosdjgpp \
358 --with-openssl=/path/to/djgpp \
359 --with-zlib=/path/to/djgpp \
360 --without-libpsl \
361 --disable-shared
362```
364```sh
365cmake . \
366 -DCMAKE_SYSTEM_NAME=DOS \
367 -DCMAKE_C_COMPILER_TARGET=i586-pc-msdosdjgpp \
368 -DCMAKE_C_COMPILER=/path/to/djgpp/bin/i586-pc-msdosdjgpp-gcc \
369 -DWATT_ROOT=/path/to/djgpp/net/watt \
370 -DOPENSSL_INCLUDE_DIR=/path/to/djgpp/include \
371 -DOPENSSL_SSL_LIBRARY=/path/to/djgpp/lib/libssl.a \
372 -DOPENSSL_CRYPTO_LIBRARY=/path/to/djgpp/lib/libcrypto.a \
373 -DZLIB_INCLUDE_DIR=/path/to/djgpp/include \
374 -DZLIB_LIBRARY=/path/to/djgpp/lib/libz.a \
375 -DCURL_USE_LIBPSL=OFF
376```
378Notes:
380- Requires DJGPP 2.04 or greater.
382- Compile Watt-32 (and OpenSSL) with the same version of DJGPP. Otherwise
383 things go wrong because things like FS-extensions and `errno` values have
384 been changed between releases.
386## AmigaOS
388You can use either autotools or CMake:
390```sh
391./configure \
392 CC=/opt/amiga/bin/m68k-amigaos-gcc \
393 AR=/opt/amiga/bin/m68k-amigaos-ar \
394 RANLIB=/opt/amiga/bin/m68k-amigaos-ranlib \
395 --host=m68k-amigaos \
396 --with-amissl \
397 CFLAGS='-O0 -msoft-float -mcrt=clib2' \
398 CPPFLAGS=-I/path/to/AmiSSL/Developer/include \
399 LDFLAGS=-L/path/to/AmiSSL/Developer/lib/AmigaOS3 \
400 LIBS='-lnet -lm -latomic' \
401 --without-libpsl \
402 --disable-shared
403```
405```sh
406cmake . \
407 -DAMIGA=1 \
408 -DCMAKE_SYSTEM_NAME=Generic \
409 -DCMAKE_C_COMPILER_TARGET=m68k-unknown-amigaos \
410 -DCMAKE_C_COMPILER=/opt/amiga/bin/m68k-amigaos-gcc \
411 -DCMAKE_C_FLAGS='-O0 -msoft-float -mcrt=clib2' \
412 -DAMISSL_INCLUDE_DIR=/path/to/AmiSSL/Developer/include \
413 -DAMISSL_STUBS_LIBRARY=/path/to/AmiSSL/Developer/lib/AmigaOS3/libamisslstubs.a \
414 -DAMISSL_AUTO_LIBRARY=/path/to/AmiSSL/Developer/lib/AmigaOS3/libamisslauto.a \
415 -DCURL_USE_LIBPSL=OFF
416```
418## Important static libcurl usage note
420When building an application that uses the static libcurl library on Windows,
421you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker looks
422for dynamic import symbols.
424## Legacy Windows and SSL
426Schannel (from Windows SSPI), is the native SSL library in Windows. Schannel
427in earlier Windows versions may be unable to connect to servers that no longer
428support the legacy handshakes and algorithms used by those versions. If you
429are using curl in such Windows versions you should choose another SSL backend
430such as OpenSSL.
432# Android
434When building curl for Android you can either use CMake or `configure`.
436Before you can build curl for Android, you need to install the Android NDK
437first. This can be done using the SDK Manager that is part of Android Studio.
438Once you have installed the Android NDK, you need to figure out where it has
439been installed and then set up some environment variables before launching
440the build.
442Examples to compile for `aarch64` and API level 29:
444with CMake, where `ANDROID_NDK_HOME` points into your NDK:
446```sh
447cmake . \
448 -DANDROID_ABI=arm64-v8a \
449 -DANDROID_PLATFORM=android-29 \
450 -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_HOME"/build/cmake/android.toolchain.cmake \
451 -DCURL_ENABLE_SSL=OFF \
452 -DCURL_USE_LIBPSL=OFF
453```
455with `configure`, on macOS:
457```sh
458export ANDROID_NDK_HOME="$HOME"/Library/Android/sdk/ndk/25.1.8937393 # Point into your NDK
459# Same tag for Apple Silicon. Other OS values here:
460# https://developer.android.com/ndk/guides/other_build_systems#overview
461export HOST_TAG=darwin-x86_64
462export TOOLCHAIN="$ANDROID_NDK_HOME"/toolchains/llvm/prebuilt/$HOST_TAG
463export AR="$TOOLCHAIN"/bin/llvm-ar
464export AS="$TOOLCHAIN"/bin/llvm-as
465export CC="$TOOLCHAIN"/bin/aarch64-linux-android29-clang
466export CXX="$TOOLCHAIN"/bin/aarch64-linux-android29-clang++
467export LD="$TOOLCHAIN"/bin/ld
468export RANLIB="$TOOLCHAIN"/bin/llvm-ranlib
469export STRIP="$TOOLCHAIN"/bin/llvm-strip
470```
472When building on Linux or targeting other API levels or architectures, you need
473to adjust those variables accordingly. After that you can build curl like this:
475 ./configure --host aarch64-linux-android --with-pic --disable-shared
477Note that this does not give you SSL/TLS support. If you need SSL/TLS, you
478have to build curl with an SSL/TLS library, e.g. OpenSSL, because it is
479impossible for curl to access Android's native SSL/TLS layer. To build curl
480for Android using OpenSSL, follow the OpenSSL build instructions and then
481install `libssl.a` and `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy
482`include/openssl` to `$TOOLCHAIN/sysroot/usr/include`. Now you can build curl
483for Android using OpenSSL like this:
485```sh
486# For AWS-LC/BoringSSL/OpenSSL. In general, you need to the SSL/TLS layer's
487# transitive dependencies if you are linking statically.
488export LIBS='-lssl -lcrypto -lc++'
489./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN"/sysroot/usr
490```
492# IBM i
494For IBM i (formerly OS/400), you can use curl in two different ways:
496- Natively, running in the **ILE**. The obvious use is being able to call curl
497 from ILE C or RPG applications.
498- You need to build this from source. See `projects/OS400/README` for the ILE
499 specific build instructions.
500- In the **PASE** environment, which runs AIX programs. curl is built as it
501 would be on AIX.
502- IBM provides builds of curl in their Yum repository for PASE software.
503- To build from source, follow the Unix instructions.
505There are some additional limitations and quirks with curl on this platform;
506they affect both environments.
508## Multi-threading notes
510By default, jobs in IBM i does not start with threading enabled. (Exceptions
511include interactive PASE sessions started by `QP2TERM` or SSH.) If you use
512curl in an environment without threading when options like asynchronous DNS
513were enabled, you get messages like:
515```
516getaddrinfo() thread failed to start
517```
519Do not panic. curl and your program are not broken. You can fix this by:
521- Set the environment variable `QIBM_MULTI_THREADED` to `Y` before starting
522 your program. This can be done at whatever scope you feel is appropriate.
523- Alternatively, start the job with the `ALWMLTTHD` parameter set to `*YES`.
525# Cross compile
527Download and unpack the curl package.
529`cd` to the new directory. (e.g. `cd curl-7.12.3`)
531Set environment variables to point to the cross-compile toolchain and call
532configure with any options you need. Be sure and specify the `--host` and
533`--build` parameters at configuration time. The following script is an example
534of cross-compiling for the IBM 405GP PowerPC processor using the toolchain on
535Linux.
537```sh
538export PATH="$PATH":/opt/hardhat/devkit/ppc/405/bin
539export CPPFLAGS=-I/opt/hardhat/devkit/ppc/405/target/usr/include
540export AR=ppc_405-ar
541export AS=ppc_405-as
542export LD=ppc_405-ld
543export RANLIB=ppc_405-ranlib
544export CC=ppc_405-gcc
545export NM=ppc_405-nm
547./configure \
548 --target=powerpc-hardhat-linux \
549 --host=powerpc-hardhat-linux \
550 --build=i586-pc-linux-gnu \
551 --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
552 --exec-prefix=/usr/local
553```
555The `--prefix` parameter specifies where curl gets installed. If `configure`
556completes, do `make` and `make install` as usual.
558In some cases, you may be able to simplify the above commands to as little as:
560 ./configure --host=ARCH-OS
562# REDUCING SIZE
564There are a number of configure options that you can use to reduce the size of
565libcurl for embedded applications where binary size is an important factor.
566First, be sure to set the `CFLAGS` variable when configuring with any relevant
567compiler optimization flags to reduce the size of the binary. For gcc, this
568would mean at minimum the `-Os` option, and others like the following that
569may be relevant in some environments: `-march=X`, `-mthumb`, `-m32`,
570`-mdynamic-no-pic`, `-flto`, `-fdata-sections`, `-ffunction-sections`,
571`-fno-unwind-tables`, `-fno-asynchronous-unwind-tables`,
572`-fno-record-gcc-switches`, `-fsection-anchors`, `-fno-plt`,
573`-Wl,--gc-sections`, `-Wl,-dead_strip` (Apple), `-Wl,-Bsymbolic`, `-Wl,-s`
575For example, this is how to combine a few of these options:
577 ./configure CC=gcc CFLAGS='-Os -ffunction-sections' LDFLAGS='-Wl,--gc-sections' ...
579Note that newer compilers often produce smaller code than older versions
580due to improved optimization.
582Be sure to specify as many `--disable-` and `--without-` flags on the
583configure command-line as you can to disable all the libcurl features that you
584know your application is not going to need. Besides specifying the
585`--disable-PROTOCOL` flags for all the types of URLs your application do not
586use, here are some other flags that can reduce the size of the library by
587disabling support for some features (run `./configure --help` to see them all):
589- `--disable-aws` (cryptographic authentication)
590- `--disable-basic-auth` (cryptographic authentication)
591- `--disable-bearer-auth` (cryptographic authentication)
592- `--disable-digest-auth` (cryptographic authentication)
593- `--disable-http-auth` (all HTTP authentication)
594- `--disable-kerberos-auth` (cryptographic authentication)
595- `--disable-negotiate-auth` (cryptographic authentication)
596- `--disable-alt-svc` (HTTP Alt-Svc)
597- `--disable-ares` (the C-ARES DNS library)
598- `--disable-cookies` (HTTP cookies)
599- `--disable-dateparse` (date parsing for time conditionals)
600- `--disable-dnsshuffle` (internal server load spreading)
601- `--disable-doh` (DNS-over-HTTP)
602- `--disable-form-api` (POST form API)
603- `--disable-get-easy-options` (lookup easy options at runtime)
604- `--disable-headers-api` (API to access headers)
605- `--disable-hsts` (HTTP Strict Transport Security)
606- `--disable-ipv6` (IPv6)
607- `--disable-libcurl-option` (--libcurl C code generation support)
608- `--disable-manual` (--manual built-in documentation)
609- `--disable-mime` (MIME API)
610- `--disable-netrc` (.netrc file)
611- `--disable-progress-meter` (graphical progress meter in library)
612- `--disable-proxy` (HTTP and SOCKS proxies)
613- `--disable-socketpair` (socketpair for asynchronous name resolving)
614- `--disable-threaded-resolver` (threaded name resolver)
615- `--disable-unix-sockets` (Unix sockets)
616- `--disable-verbose` (eliminates debugging strings and error code strings)
617- `--disable-versioned-symbols` (versioned symbols)
618- `--enable-symbol-hiding` (eliminates unneeded symbols in the shared library)
619- `--without-brotli` (Brotli on-the-fly decompression)
620- `--without-libpsl` (Public Suffix List in cookies)
621- `--without-nghttp2` (HTTP/2 using nghttp2)
622- `--without-ngtcp2` (HTTP/2 using ngtcp2)
623- `--without-zstd` (Zstd on-the-fly decompression)
624- `--without-libidn2` (internationalized domain names)
625- `--without-ssl` (SSL/TLS)
626- `--without-zlib` (gzip/deflate on-the-fly decompression)
628You can find the CMake-equivalents in
629[INSTALL-CMAKE.md](https://github.com/curl/curl/blob/master/docs/INSTALL-CMAKE.md).
631Be sure also to strip debugging symbols from your binaries after compiling
632using `strip` or an option like `-s`. If space is tight, you may be able
633to gain a few bytes by removing unneeded sections of the shared library using
634the `-R` option to objcopy (e.g. the `.comment` section).
636Using these techniques it is possible to create a basic HTTP-only libcurl
637shared library for i386 Linux platforms that is only 137 KiB in size
638(as of libcurl version 8.13.0, using gcc 14.2.0).
640You may find that statically linking libcurl to your application results in a
641lower total size than dynamically linking.
643The curl test harness can detect the use of some, but not all, of the
644`--disable` statements suggested above. Use of these can cause tests relying
645on those features to fail. The test harness can be manually forced to skip the
646relevant tests by specifying certain key words on the `runtests.pl` command
647line. Following is a list of appropriate key words for those configure options
648that are not automatically detected:
650- `--disable-cookies` !cookies
651- `--disable-dateparse` !RETRY-AFTER !`CURLOPT_TIMECONDITION` !`CURLINFO_FILETIME` !`If-Modified-Since` !`curl_getdate` !`-z`
652- `--disable-libcurl-option` !`--libcurl`
653- `--disable-verbose` !verbose\ logs
655# Ports
657This is a probably incomplete list of known CPU architectures and operating
658systems that curl has been compiled for. If you know a system curl compiles
659and runs on, that is not listed, please let us know.
661## 108 Operating Systems
663 AIX, AmigaOS, Android, ArcaOS, Aros, Atari FreeMiNT, Azure Sphere, BeOS,
664 Blackberry 10, Blackberry Tablet OS, Cell OS, Cesium, CheriBSD, Chrome OS,
665 Cisco IOS, DG/UX, DR DOS, Dragonfly BSD, eCOS, FreeBSD, FreeDOS, FreeRTOS,
666 Fuchsia, Garmin OS, Genode, Haiku, HardenedBSD, HP-UX, Hurd, IBM I,
667 illumos, Integrity, iOS, ipadOS, IRIX, KasperskyOS, Linux, Lua RTOS,
668 Mac OS 9, macOS, Maemo, Mbed, Meego, Micrium, MINIX, Minoca, Moblin,
669 MorphOS, MPE/iX, MS-DOS, NCR MP-RAS, NetBSD, Netware, NextStep,
670 Nintendo 3DS, Nintendo Switch, NonStop OS, NuttX, OpenBSD, OpenStep,
671 Orbis OS, OS/2, OS21, PikeOS, Plan 9, PlayStation Portable, QNX, Qubes OS,
672 ReactOS, Redox, RISC OS, ROS, RTEMS, Sailfish OS, SCO Unix, Serenity,
673 SINIX-Z, SkyOS, SmartOS, Solaris, Sortix, SunOS, Syllable OS, Symbian,
674 Tizen, TPF, Tru64, tvOS, ucLinux, Ultrix, UNICOS, UnixWare, visionOS, VMS,
675 vxWorks, watchOS, Wear OS, WebOS, Wii System Software, Wii U, Windows,
676 Xbox System, Xenix, z/OS, z/TPF, z/VM, z/VSE, Zephyr
678## 28 CPU Architectures
680 Alpha, ARC, ARM, AVR32, C-SKY, CompactRISC, Elbrus, ETRAX, HP-PA, Itanium,
681 LoongArch, m68k, m88k, MicroBlaze, MIPS, Nios, OpenRISC, POWER, PowerPC,
682 RISC-V, s390, SH4, SPARC, Tilera, VAX, x86, Xtensa, z/arch
Diagnostics4 git calls · 33 ms
CallStatusSizeTime033 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=4
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch20011 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=25
git.response.bytes=11168
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.wants=5ae376d11802a17ff45ed32e467278126c4d296b
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=11168
git.pkt.payload.max=11147
git.sideband.band1.bytes=11146
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e2a0c78deb1293
Request
a2a81939…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format