CURLOPT_NETRC(3)

💅 CURLOPT_NETRC — enable use of .netrc

okay bestie, this one's from the libcurl manual (that's curl_easy_setopt(3) territory, iykyk) and it's literally all about letting libcurl peek at your ~/.netrc file. let's get into it 🎀

---

✨ NAME ✨

CURLOPT_NETRC — enable use of .netrc

---

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);

---

🌸 DESCRIPTION 🌸

so this parameter is the vibe check between two sources of creds: the usernames and passwords chilling in your ~/.netrc file vs. the ones sitting right there in the URL you handed to CURLOPT_URL(3). it sets the preference level between them, no cap.

if the NETRC environment variable is set, that filename gets used as the netrc file instead. (Added in 8.16.0 ✨)

on Windows, libcurl primarily checks for .netrc in %HOME%. if %HOME% is not set on Windows, libcurl falls back to %USERPROFILE%. and if the file does not exist, it falls back to checking whether there's instead a file named _netrc — yeah, using an underscore instead of period. iconic little fallback chain tbh.

you can also tell libcurl a totally different filename to use with CURLOPT_NETRC_FILE(3) 🫶

libcurl uses a username (and supplied or prompted password) supplied with CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of the options controlled by this parameter. so those win, periodt.

only machine name, username and password are taken into account (init macros and similar things are not supported — sorry bestie 💀).

the netrc file provides credentials for a hostname independent of which protocol and port number that are used. cute and simple.

⚠️ libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user. no seriously, lock that file down 🙈

level is a long that should be set to one of the values described below 👇

• CURL_NETRC_IGNORED (0) — libcurl ignores the .netrc file. this is the default, bestie, so nothing spicy happens unless you ask for it.
• CURL_NETRC_OPTIONAL (1) — the use of the .netrc file is optional, and information in the URL is to be preferred. the file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that machine, whichever information is not specified.
• CURL_NETRC_REQUIRED (2) — the use of the .netrc file is required, and any credential information present in the URL is ignored. the file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that machine, whichever information is not specified.

---

🧚 FILE FORMAT 🧚

the .netrc file format is simple: you specify lines with a machine name and follow the login and password that are associated with that machine. slay, honestly.

each field is provided as a sequence of letters that ends with a space or newline. starting in 7.84.0, libcurl also supports quoted strings. they start and end with double quotes and support the escaped special letters ", n, r, and t. quoted strings are the only way a space character can be used in a username or password. the way that's such a niche need but okay go off 💅

• machine <name> — provides credentials for a host called name. libcurl searches the .netrc file for a machine token that matches the hostname specified in the URL. once a match is made, the subsequent tokens are processed, stopping when the end of file is reached or another machine is encountered.
• default — this is the same as machine name except that default matches any name. there can be only one default token, and it must be after all machine tokens. to provide a default anonymous login for hosts that are not otherwise matched, add a line similar to this in the end:

default login anonymous password user@domain

• login <name> — the username string for the remote machine.
• password <secret> — supply a password. if this token is present, curl supplies the specified string if the remote server requires a password as part of the login process. note that if this token is present in the .netrc file you really should make sure the file is not readable by anyone besides the user. 🔐
• macdef <name> — define a macro. this feature is not supported by libcurl. in order for the rest of the .netrc to still work fine, libcurl properly skips every definition done with macdef that it finds. bestie just ignores it and moves on, we love a graceful skip ✨

---

🎀 DEFAULT 🎀

CURL_NETRC_IGNORED

---

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. every single one. main character energy 👑

---

🔥 EXAMPLE 🔥

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
    curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
    result = curl_easy_perform(curl);
  }
}

---

⭐ HISTORY ⭐

CURL_NETRC_* enums became long types in 8.13.0. prior to this version a long cast was necessary when passed to curl_easy_setopt(3). glow-up for real 💅

---

💜 AVAILABILITY 💜

Added in curl 7.1 — she's been here a minute, an OG 🫶

---

🍓 RETURN VALUE 🍓

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3). no mystery, just check the code 😭

---

🌸 SEE ALSO 🌸

• CURLOPT_NETRC_FILE(3)
• CURLOPT_USERNAME(3)
• CURLOPT_USERPWD(3)

---

k bye bestie, go make sure that .netrc is chmod'd properly before you ship anything 💖 this page came straight from libcurl, dated 2026-10-12 — mwah, and remember: credentials in the URL win the preference battle, so don't @ me when your netrc gets ignored 🎀✨