1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_PROXY
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPPROXYTUNNEL (3)
9  - CURLOPT_PRE_PROXY (3)
10  - CURLOPT_PROXYPORT (3)
11  - CURLOPT_PROXYTYPE (3)
12---
13
14# NAME
15
16CURLOPT_PROXY - proxy to use
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
24~~~
25
26# DESCRIPTION
27
28Set the *proxy* to use for transfers with this easy handle. The parameter
29should be a char * to a null-terminated string holding the hostname or dotted
30numerical IP address. A numerical IPv6 address must be written within
31[brackets].
32
33To specify port number in this string, append :[port] to the end of the host
34name. The proxy's port number may optionally (but discouraged) be specified
35with the separate option CURLOPT_PROXYPORT(3). If not specified, libcurl
36defaults to using port 1080 for proxies.
37
38The proxy string may be prefixed with [scheme]:// to specify which kind of
39proxy is used.
40
41## http://
42
43HTTP Proxy. Default when no scheme or proxy type is specified.
44
45## https://
46
47HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it
48also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and
49wolfSSL.)
50
51This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to
52**CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy.
53
54## socks4://
55
56SOCKS4 Proxy.
57
58## socks4a://
59
60SOCKS4a Proxy. Proxy resolves URL hostname.
61
62## socks5://
63
64SOCKS5 Proxy.
65
66## socks5h://
67
68SOCKS5 Proxy. Proxy resolves URL hostname.
69
70Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify
71which kind of proxy the string identifies.
72
73When you tell the library to use an HTTP proxy, libcurl transparently converts
74operations to HTTP even if you specify an FTP URL etc. This may have an impact
75on what other features of the library you can use, such as
76CURLOPT_QUOTE(3) and similar FTP specifics that do not work unless you
77tunnel through the HTTP proxy. Such tunneling is activated with
78CURLOPT_HTTPPROXYTUNNEL(3).
79
80Setting the proxy string to "" (an empty string) explicitly disables the use
81of a proxy, even if there is an environment variable set for it.
82
83A proxy host string can also include protocol scheme (http://) and embedded
84user + password.
85
86Unix domain sockets are supported for socks proxies since 7.84.0. Set
87localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock
88
89The application does not have to keep the string around after setting this
90option.
91
92When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*,
93cannot be used.
94
95# Environment variables
96
97libcurl respects the proxy environment variables named **http_proxy**,
98**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy
99for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is
100considered. **all_proxy** is used if no protocol specific proxy was set.
101
102If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of
103setting the CURLOPT_NOPROXY(3) option.
104
105The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment
106variables.
107
108# DEFAULT
109
110Default is NULL, meaning no proxy is used.
111
112When you set a hostname to use, do not assume that there is any particular
113single port number used widely for proxies. Specify it!
114
115# PROTOCOLS
116
117All except file://. Note that some protocols do not work well over proxy.
118
119# EXAMPLE
120
121~~~c
122int main(void)
123{
124  CURL *curl = curl_easy_init();
125  if(curl) {
126    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
127    curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
128    curl_easy_perform(curl);
129  }
130}
131~~~
132
133# AVAILABILITY
134
135Since 7.14.1 the proxy environment variable names can include the protocol
136scheme.
137
138Since 7.21.7 the proxy string supports the socks protocols as "schemes".
139
140Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
141error.
142
143# RETURN VALUE
144
145Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
146CURLE_OUT_OF_MEMORY if there was insufficient heap space.
147