Proxy password with special characters

An @, :, # or / in a proxy password breaks the URL it sits in. Percent-encode the login, or hand it over in a separate field.

6 min readTested on curl 8.23 · requests 2.34 · httpx 0.28 · undici 8.12 · axios 1.21 · Go 1.26
A proxy URL with the password p@ss:w0rd unencoded is split at the wrong @ and colon, so the parser reads w0rd as the port; percent-encoded as p%40ss%3Aw0rd it parses as intended.How the parser splits a proxy URLhttp://alice:p@ss:w0rd@via.proxies.vision:9000login ends at the first @ · host “ss” · port “w0rd”Failed to parse: 'ss:w0rd' is not a valid host or porthttp://alice:p%40ss%3Aw0rd@via.proxies.vision:9000quote(password, safe="") · encodeURIComponent(password)200curl 8.23 · requests 2.34 · httpx 0.28 · undici 8.12 · axios 1.21 · Go 1.26 · November 5, 2026

In short

Encode the username and password before you build http://user:pass@host:port: @ becomes %40, : %3A, # %23, / %2F, % %25. Or skip the URL and pass the login in a separate option. Two exceptions below: curl’s -U and axios’ HTTP_PROXY.

quote(pw, safe="")encodeURIComponent(pw)

A proxy URL packs four things into one string: scheme://user:password@host:port. The parser finds them by their separators. Put @ or : inside the password and the separators no longer mean what you meant.

For the password p@ss:w0rd#1%2F, every parser we tried ended the login at the first @. What followed, ss:w0rd, became host and port, and w0rd is not a number. The # starts a fragment, so the rest of the URL disappears before anyone looks at the real host. The %2F is the quiet one: a parser that decodes the login turns it into /, and the proxy gets the wrong password without any parse error.

Percent-encoding the login takes the separators out of it. The parser splits the URL correctly, then decodes %40 back to @ before it sends Proxy-Authorization.

We gave a local Squid proxy the user alice with the password p@ss:w0rd#1%2F and called it from each tool three ways: the password as is in the URL, percent-encoded in the URL, and through the tool’s own login option.

ToolRaw in URLEncoded in URLSeparate login
curl 8.23(5) Unsupported proxy syntax … Port number was not a decimal number between 0 and 65535200-U: 407 (decodes %2F)
requests 2.34.2InvalidURL: Failed to parse: 'ss:w0rd' is not a valid host or port200none
httpx 0.28.1InvalidURL: Invalid port: 'w0rd'200Proxy(auth=…): 200
aiohttp 3.14.5InvalidURL200proxy_auth: 200
undici 8.12.4 (Node 24)TypeError: Invalid URL200token: 200
axios 1.21.0HTTP_PROXY: Invalid URLHTTP_PROXY: 407proxy.auth: 200
Go 1.26 net/httpinvalid port ":w0rd" after host200url.UserPassword: 200
Fig. 1 — Squid 6.13 with basic auth, target http://example.com/, November 5, 2026. 200 means the proxy accepted the login.

A parse error names your password

Look at the messages: 'ss:w0rd', 'w0rd'. They quote pieces of the password, and in a log they are part of your secret. If you see a host or port in an error that you never typed, it came from your login.

The encoding is the same everywhere

Every tool that failed on the raw URL accepted the encoded one, except axios. The encoding is standard URL encoding of the user-info part, so quote() output works in curl and Go, and encodeURIComponent() output works in Python.

curl -U decodes percent signs

-U alice:p@ss:w0rd#1%2F looks safe, since there is no URL to break. But curl decoded %2F to / before sending, and Squid answered 407. In -U, only a literal % needs care: write it as %25.

407-U 'alice:p@ss:w0rd#1%2F'sent p@ss:w0rd#1/
200-U 'alice:p@ss:w0rd#1%252F'% written as %25
200-x 'http://alice:p%40ss%3Aw0rd%231%252F@host:3128'fully encoded URL

axios and HTTP_PROXY

axios reads HTTP_PROXY itself. With the password encoded, it sent the encoded text as the password and got 407; unencoded, the variable isn’t a valid URL. Use the proxy option with auth: { username, password }, which takes the password as is. More on axios and proxies.

Python’s quote() keeps the slash

urllib.parse.quote() leaves / alone unless you pass safe="". For the password se/cret@7, requests failed with Failed to parse: 'bob:se' is not a valid host or port; with safe="" it got 200.

A setup that works

Both ran unchanged against our gateway and, with the host swapped, against the Squid with p@ss:w0rd#1%2F and se/cret@7. PROXY_USER and PROXY_PASS come from the environment.

proxy_password.py
import os
from urllib.parse import quote

import requests  # pip install requests

user = quote(f"{os.environ['PROXY_USER']}-country-de", safe="")
password = quote(os.environ["PROXY_PASS"], safe="")  # safe="": also encode "/", which quote() keeps by default
proxy = f"http://{user}:{password}@via.proxies.vision:9000"

r = requests.get("https://ipinfo.io/json", proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.status_code, r.json()["country"])
proxy_password.mjs
import { ProxyAgent, fetch } from "undici"; // npm i undici

const user = encodeURIComponent(`${process.env.PROXY_USER}-country-de`);
const pass = encodeURIComponent(process.env.PROXY_PASS);
const dispatcher = new ProxyAgent(`http://${user}:${pass}@via.proxies.vision:9000`);

const res = await fetch("https://ipinfo.io/json", { dispatcher });
console.log(res.status, (await res.json()).country);
txt
200 DE

On the command line

curl -x http://via.proxies.vision:9000 -U "$PROXY_USER-country-de:$PROXY_PASS" https://ipinfo.io/json keeps the login out of the URL. It is safe as long as the password has no %; if it does, write each one as %25. If curl still answers 407.

For a password of only letters and digits the encoding changes nothing, so there is no reason to leave it out: the same code keeps working when a password with symbols comes along. Targeting goes into the username before encoding: USER-country-de-session-job1-lifetime-10 on port 10000 keeps one IP for ten minutes.

How do I put a password with @ into a proxy URL?
Percent-encode the username and the password, not the whole URL: @ becomes %40, : becomes %3A, # becomes %23, / becomes %2F and % itself becomes %25. In Python use urllib.parse.quote(password, safe=""), in JavaScript encodeURIComponent(password), in Go url.UserPassword(user, password).
Why does curl say 'Port number was not a decimal number between 0 and 65535'?
curl split the proxy URL at an @ or : inside the password, so part of the password ended up where the port belongs. Encode the password in the URL, or pass it with -U user:password, where only a % needs escaping (as %25).
Why does quote() still fail on a password with a slash?
urllib.parse.quote keeps / unencoded by default (safe="/"). In a proxy URL the slash then starts the path, and requests failed with "Failed to parse: 'bob:se' is not a valid host or port" for the password se/cret@7. Pass safe="".
Why does axios get a 407 with an encoded password in HTTP_PROXY?
axios 1.21 took the password from HTTP_PROXY as written and sent it still percent-encoded, so the proxy saw p%40ss… instead of p@ss…. An unencoded one isn't a valid URL. Pass the login through axios' proxy.auth option instead, which takes it as plain text.

Residential proxies, pay per GB

HTTP and SOCKS5. Country, city and sticky sessions in the username. No subscription.