How do I decode a percent-encoded URL with plus signs as spaces?

Dark navy cover card with the title 'How do I decode a percent-encoded URL with plus signs as spaces?' in white and a green accent bar

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.pdf stays a+b.pdf in the path. Running a form decoder over the whole URL renames it.
  • Double encoding. %2520 means the value was encoded twice: one decode gives %20, a second gives the space. The WHATWG spec's own example shows 2%20 encoding to 2%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 %2B back 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.

Sources