Proxy Formats Explained

Common formats

Every format holds the same four facts. They differ in order, separators and whether the protocol is included.

The URL form follows the URI syntax of RFC 3986, where the part before @ is the userinfo. Tools that take a single proxy string, such as curl's -x option and Python Requests' proxies setting, expect this form. Tools with a settings screen usually split the fields: Playwright's proxy option takes a server plus separate username and password.

Chrome's command-line switch is the odd one out. Chromium's network settings page documents --proxy-server with a scheme, host and port, and there is no place in it for a username and password. Authenticated proxies in Chrome need an automation tool or extension that answers the proxy's login challenge; the Selenium proxy authentication guide shows one way.

What the scheme changes

The scheme at the start of a URL tells the tool which protocol to speak to the proxy:

• http:// is a plain HTTP proxy. HTTPS sites still work: the tool asks the proxy to open a tunnel with CONNECT and the TLS session runs end to end.
• https:// encrypts the hop between your tool and the proxy. Only use it if the provider offers TLS on that port.
• socks5:// speaks SOCKS5, and the tool looks up the website's address itself, then sends the proxy an IP.
• socks5h:// speaks SOCKS5 but sends the hostname, so the proxy does the DNS lookup.

The difference between the last two is visible on the proxy side. On our test proxy, a socks5:// request from curl arrived as an IPv4 address, while socks5h:// arrived as the hostname api.ipify.org. With socks5://, your local DNS resolver sees every site you visit, and the answer you get may suit your location rather than the exit's. Use socks5h:// unless a tool cannot.

Special characters in passwords

RFC 3986 reserves characters such as @, :, /, ? and # as delimiters. Inside the username or password of a URL they must be percent-encoded, or the parser cuts the string in the wrong place. This is what happened with a password of p@ss:w0rd on curl 8.7.1:

# Fails: the second '@' and ':' are read as the host and port
curl -x 'http://lab-user:p@ss:w0rd@198.51.100.20:8080' https://api.ipify.org
curl: (5) Unsupported proxy syntax in 'http://lab-user:p@ss:w0rd@198.51.100.20:8080': Port number was not a decimal number between 0 and 65535

# Works: percent-encoded inside the URL
curl -x 'http://lab-user:p%40ss%3Aw0rd@198.51.100.20:8080' https://api.ipify.org

# Works: raw password in a separate option
curl -x http://198.51.100.20:8080 --proxy-user 'lab-user:p@ss:w0rd' https://api.ipify.org

The encodings you will need most: @ is %40, : is %3A, / is %2F, # is %23, ? is %3F, % is %25 and a space is %20.

Encode only inside the URL form. Separate username and password fields, curl's --proxy-user and Playwright's password all take the raw value; encoding it there makes the password wrong.

Converting between formats

Most conversion bugs come from splitting on every colon. A host:port:user:pass line has exactly three separators that matter, so split three times and keep the rest as the password. This function was tested against the same local proxy:

from urllib.parse import quote

def to_url(line: str, scheme: str = "http") -> str:
    # host:port:user:pass -> scheme://user:pass@host:port
    # maxsplit=3 keeps any ':' inside the password
    host, port, user, password = line.strip().split(":", 3)
    return f"{scheme}://{quote(user, safe='')}:{quote(password, safe='')}@{host}:{port}"

print(to_url("198.51.100.20:8080:lab-user:p@ss:w0rd"))
# http://lab-user:p%40ss%3Aw0rd@198.51.100.20:8080
print(to_url("198.51.100.20:1080:lab-user:p@ss:w0rd", "socks5h"))
# socks5h://lab-user:p%40ss%3Aw0rd@198.51.100.20:1080

One limit no script can fix: a username that itself contains : cannot be stored in a colon list at all, because there is no way to tell which colon is the separator. Keep such credentials in URL form or in separate fields.

Python Requests is strict about the URL. On Requests 2.32, a proxy string with credentials but no scheme raised InvalidProxyURL with the message that it is malformed and could be missing the host, and a socks5h:// proxy raised Missing dependencies for SOCKS support until the SOCKS extra was installed with pip install requests[socks]. The Python Requests proxy guide covers both.

Coronium connection details

Each Coronium line has five connection fields: ip_address, http_port, socks_port, proxy_login and proxy_password. The REST API v3 returns them for each of your proxies, and the dashboard shows the same details for each line. HTTP and SOCKS5 run on separate ports, so the scheme and the port have to match:

curl -x "http://PROXY_LOGIN:PROXY_PASSWORD@IP_ADDRESS:HTTP_PORT" https://api.ipify.org
curl --socks5-hostname "PROXY_LOGIN:PROXY_PASSWORD@IP_ADDRESS:SOCKS_PORT" https://api.ipify.org

An easy mistake is a SOCKS5 scheme pointed at the HTTP port, or the reverse. The connection then fails without a helpful message, because each port speaks only its own protocol.

For tools that want a colon list, assemble IP_ADDRESS:HTTP_PORT:PROXY_LOGIN:PROXY_PASSWORD for HTTP or use the SOCKS port for SOCKS5. Treat the password and any rotation link as secrets; anyone with them can use or rotate the line.

Frequently asked questions