To URL decode a string where the plus sign means a space, replace every + with a space first, then percent-decode the %XX sequences. Better still, use a form-aware decoder that does both in the right order: URLSearchParams in JavaScript, unquote_plus() in Python, urldecode() in PHP, url.QueryUnescape in Go or URLDecoder.decode() in Java.
The order matters because an encoded plus (%2B) has to survive as a real +. Do the steps the other way round and c%2B%2B turns into "c " instead of "c++".
Why a plus sign means a space only in some parts of a URL
A plus sign means a space only inside data that uses the application/x-www-form-urlencoded format: query strings and HTML form bodies. In the rest of a URL, + is just a plus.
The generic URI syntax in RFC 3986 lists + as a reserved "sub-delim" character and gives it no space meaning. Its encoding for a space is %20.
The form format comes from the WHATWG URL Standard. Its serializer writes a space as + and escapes a real plus as %2B. Its parser reverses that.
You can see the split in any browser or in Node:
const u = new URL("https://x.test/a+b?x=a+b");
u.pathname; // "/a+b" (path: plus stays a plus)
u.searchParams.get("x"); // "a b" (query: plus becomes a space)
Before you decode, ask where the string came from. A query value or a form post gets plus-as-space decoding. A path segment, a fragment or a Base64 blob does not.
The right order: replace plus signs, then percent-decode
The WHATWG form parser replaces + with a space before it percent-decodes. Step 3.4 of the algorithm says to "Replace any 0x2B (+) in name and value with 0x20 (SP)", and only the next step decodes the %XX bytes.
A bare + was a space when it was encoded. A %2B was a real plus. Percent-decode first and the two look identical.
Three values from one query string:
| Encoded | After + → space |
After percent-decoding |
|---|---|---|
caf%C3%A9+au+lait |
caf%C3%A9 au lait |
café au lait |
c%2B%2B |
c%2B%2B |
c++ |
1+1 |
1 1 |
1 1 |
The last row trips people up. If a user typed "1+1" into a form, the browser would have sent 1%2B1. A bare 1+1 in a query string really does mean "1 1".
How to decode plus signs as spaces in JavaScript
In JavaScript, URLSearchParams is the cleanest way to URL decode a query string with plus signs as spaces, because it uses the WHATWG form parser.
const params = new URLSearchParams("q=caf%C3%A9+au+lait&tag=c%2B%2B");
params.get("q"); // "café au lait"
params.get("tag"); // "c++"
decodeURIComponent() on its own leaves the plus signs alone. I ran these in Node.js v24.15.0:
decodeURIComponent("caf%C3%A9+au+lait"); // "café+au+lait"
MDN says the function "cannot be used directly to parse query parameters from a URL" and shows the fix: replace the plus signs first.
function decodeFormValue(s) {
return decodeURIComponent(s.replace(/\+/g, " "));
}
decodeFormValue("search+query%20%28correct%29"); // "search query (correct)"
Watch for one error. decodeURIComponent("100%") throws URIError: URI malformed, because a % must be followed by two hex digits. Wrap user input in try/catch.
Plus-aware decoders in Python, PHP, Go and Java
Most standard libraries ship two decoders: one that treats + as a space for form data, and one that doesn't.
| Language | Plus becomes a space | Plus stays a plus |
|---|---|---|
| JavaScript | URLSearchParams |
decodeURIComponent() |
| Python | urllib.parse.unquote_plus(), parse_qs() |
urllib.parse.unquote() |
| PHP | urldecode() |
rawurldecode() |
| Go | url.QueryUnescape() |
url.PathUnescape() |
| Java | URLDecoder.decode(s, UTF_8) |
not covered by URLDecoder |
Python. The urllib.parse docs describe unquote_plus() as "Like unquote(), but also replace plus signs with spaces, as required for unquoting HTML form values." Their example turns /El+Ni%C3%B1o/ into /El Niño/. For a whole query string, parse_qs() does the same per value.
PHP. The urldecode() manual says plus symbols "are decoded to a space character". The rawurldecode() page says it does not do that. One warning: values in $_GET and $_REQUEST are already decoded, so don't run urldecode() on them again.
Go. The net/url docs put it in one line: PathUnescape "is identical to QueryUnescape except that it does not unescape '+' to ' ' (space)."
Java. URLDecoder is a form decoder, so it always converts + to a space. Use the decode(String, Charset) overload, added in Java 10, with UTF-8. The one-argument decode(String) is deprecated. Don't use URLDecoder on a URL path.
What goes wrong when you decode the wrong way
Most plus-sign bugs come from using the right decoder on the wrong part of the URL, or decoding twice.
- Base64 in a query string. Standard Base64 uses
+. Pass it through a form decoder and every+becomes a space, which breaks the data. Send it as Base64URL or encode the plus as%2B. - Plus signs in a path. A file named
a+b.pdfstaysa+b.pdfin the path. Running a form decoder over the whole URL renames it. - Double encoding.
%2520means the value was encoded twice: one decode gives%20, a second gives the space. The WHATWG spec's own example shows2%20encoding to2%2520. Fix the encoder rather than decoding in a loop. - Double decoding. Framework query objects (such as PHP's
$_GET) are already decoded. Decoding again turns a real%2Bback into a bare plus.
My take: don't write your own plus handling unless you're stuck with decodeURIComponent. The built-in form decoders follow the spec. The hand-rolled .replace() versions are where the bugs live.
The limitation: no decoder can recover intent once it's lost. If upstream code put a phone number with a leading + in a query string without encoding it, that plus arrives as a space. Only the sender can fix it.
If the decoded value is a token, see how to decode a JWT safely. If it's Base64 text, see how to decode Base64 in Python.
FAQ
Why doesn't decodeURIComponent turn + into a space?
decodeURIComponent only decodes %XX escapes. The rule that + means a space belongs to the form-urlencoded format, so you either replace + with a space first or use URLSearchParams.
How do I send a real plus sign in a query string?
Encode it as %2B. A form decoder turns a bare + into a space, but %2B always decodes to a literal plus.
Is + or %20 correct for a space in a URL?
Both appear. %20 works everywhere in a URL. A + means a space only in query strings and form bodies that use application/x-www-form-urlencoded.
Should I decode $_GET values in PHP with urldecode?
No. PHP has already decoded $_GET and $_REQUEST, and the PHP manual warns that decoding them again can give unexpected and dangerous results.