How to Use cURL HTTP/2 on macOS

cURL is one of most powerful tools for testing HTTP traffic. We typically use cURL to interact with HTTP APIs or test websites.

~~Although cURL supports HTTP/2, the version that’s installed on macOS Sierra does not.~~ Read Update.

If you try to use the --http2 flag, you’ll receive the following error:

$ curl -I --http2 https://www.itnota.com

curl: (1) Unsupported protocol

Fortunately, we can use another installation from Homebrew alongside the default version. To do so, just type the following command in the Terminal window (assuming you already have Homebrew installed):

$ brew install curl —with-nghttp2

That’s it.

Keep in mind that this installation does not replace the default curl in the system and this can be a good or bad thing for you.

If you want to keep things separately, you’re done as you can always call the 2nd curl by typing its full path:

$ /usr/local/opt/curl/bin/curl -I --http2 https://www.itnota.com

If you check the version of the two in this example:

# Default Version

$ curl --version

curl 7.51.0 (x86_64-apple-darwin16.0) libcurl/7.51.0 SecureTransport zlib/1.2.8

Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp

Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets

# Homebrew Version

$ /usr/local/opt/curl/bin/curl --version

curl 7.54.0 (x86_64-apple-darwin16.6.0) libcurl/7.54.0 OpenSSL/1.0.2l zlib/1.2.8 nghttp2/1.23.1

Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp

Features: IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy

If you want to set the curl you installed from Homebrew as the default, keep reading.

Set Homebrew cURL as the Default

There are several ways to set the new version as your default curl, but I believe the best and safest way to do it was already suggested at the end of installation process.

Notice that after installing the curl from Homebrew you’ll see a warning and instruction. If you missed it, it will look similar to this:

[...]

######################################################################## 100.0%

==> ./configure --disable-silent-rules --prefix=/usr/local/Cellar/curl/7.54.0 --with-==> make install==>

Caveats

This formula is keg-only, which means it was not symlinked into /usr/local,

because macOS already provides this software and installing another version in

parallel can cause all kinds of trouble.

If you need to have this software first in your PATH run:

echo 'export PATH="/usr/local/opt/curl/bin:$PATH"' >> ~/.bash_profile

For compilers to find this software you may need to set:

LDFLAGS: -L/usr/local/opt/curl/lib

CPPFLAGS: -I/usr/local/opt/curl/include

For pkg-config to find this software you may need to set:

PKG_CONFIG_PATH: /usr/local/opt/curl/lib/pkgconfig

[...]

Just following the instruction provided, type in the following:

$ echo 'export PATH="/usr/local/opt/curl/bin:$PATH"' >> ~/.bash_profile

You need to restart terminal and this time if you call curl without the full path, it will run the Homebrew version.

If you need to refer back to the default macOS version, just edit your ~/.bash_profile file by typing the following command:

$ sudo nano ~/.bash_profile

Look for this line:

export PATH="/usr/local/opt/curl/bin:$PATH"

and comment it out like so:

# export PATH="/usr/local/opt/curl/bin:$PATH"

And press CTRL-X and Yes to exit and save it.

Now you can test it using —http2 flag:

$ curl -I --http2 https://www.itnota.com

Update

Update on 5/21/2019: There are two updates that render this post obsolete.

First update is that the version of curl installed on macOS now supports HTTP/2.

The second update is that Homebrew has removed the –with-nghttp2 option from curl which makes the instructions not accurate.

You can still follow the instructions above for Homebrew version of curl only if you substitute it with the curl-openssl and its corresponding path instead.

So you can uninstall Homebrew curl by running the following:

$ brew uninstall curl

Then install curl-openssl by running the following:

$ brew install curl-openssl

That’s it. You don’t even need to specify any flag such as --with-nghttp2 on the curl-openssl install. It will just work. You just need to pay attention to the path where the curl is installed. It is

/usr/local/opt/curl-openssl/bin/curl

The latest comparison between the two versions of curl:

# Default Version

$ curl --version

curl 7.54.0 (x86_64-apple-darwin18.0) libcurl/7.54.0 LibreSSL/2.6.5 zlib/1.2.11 nghttp2/1.24.1

Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp

Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz HTTP2 UnixSockets HTTPS-proxy

# Homebrew Version

$ /usr/local/opt/curl-openssl/bin/curl --version

curl 7.65.0 (x86_64-apple-darwin18.6.0) libcurl/7.65.0 OpenSSL/1.0.2r zlib/1.2.11 brotli/1.0.7 c-ares/1.15.0 libssh2/1.8.2 nghttp2/1.38.0 librtmp/2.3

Release-Date: 2019-05-22

Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp

Features: AsynchDNS brotli GSS-API HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz Metalink NTLM NTLM_WB SPNEGO SSL TLS-SRP UnixSockets