Home / Guides / URL encoding guide

URL Encoding Explained

A practical guide to percent-encoding: what it is, which characters need it, how paths and query strings differ, and the mistakes that break links.

Try it now: URL encoder and URL decoder.

What is URL encoding?

URL encoding, also called percent-encoding, is the method that lets a URL carry any text. A URL may only contain a limited set of ASCII characters. Every other byte is replaced by a percent sign and two hex digits: a space is %20, é is %C3%A9, and & inside a value is %26. The rules come from RFC 3986, and the form variant from the WHATWG URL standard.

Why it is needed

  1. Safety of structure. The characters ? # & = / mean something. If your data contains one, it must be encoded, or the receiver reads it as syntax.
  2. Characters that are not allowed, such as spaces, quotes and angle brackets, would be mangled or rejected by software on the way.
  3. Non-ASCII text. URLs were designed for ASCII. Accents, Arabic, Chinese and emoji travel as UTF-8 bytes, each written as %XX.

The three groups of characters

  • Unreserved: A-Z a-z 0-9 - . _ ~. Always safe.
  • Reserved: : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Safe in their role, encoded when they are data.
  • Everything else: space, " % < > \ ^ ` { | } and all non-ASCII. Always encoded.

The full table of codes is on the percent-encoding page.

How to encode, step by step

  1. Split your URL into parts: scheme, host, path, query, fragment.
  2. Encode each value separately: every path segment, every query key and value.
  3. Put the parts together with the real separators (/, ?, &, =, #).
  4. Encode once, and only once, at the moment of building the URL. Keep data raw everywhere else.

Different rules for different parts

PartNotes
HostNot percent-encoded. International domain names use Punycode (xn--).
PathEncode each segment. / separates segments, so a slash in a name must be %2F. A space is %20, never +.
QueryEncode keys and values. & and = are separators. Space is %20 or +.
FragmentEncode like a value. The fragment is never sent to the server.
Username and passwordEncode : @ /. Better still, do not put credentials in a URL.

%20 or +?

RFC 3986 knows only %20. The + as a space comes from HTML forms (application/x-www-form-urlencoded) and applies to the query part. A decoder for a path must not turn + into a space, and a real plus in a query must be %2B. When in doubt, send %20.

Unicode and UTF-8

Encode text as UTF-8 first, then percent-encode the bytes. Old systems used Windows-1252 or ISO-8859-1, where é is %E9. Modern browsers and APIs expect UTF-8 (%C3%A9). If a link shows strange characters like é, the two sides disagree about the charset.

Double encoding

If a value is encoded twice, % becomes %25 and %20 turns into %2520. Common causes: a framework that already encodes parameters while you encoded them too, redirects that wrap a URL inside another URL, and copying an encoded link into a field that encodes again. Fix it at the source. To repair a string, use the URL decoder with Decode repeatedly. (Putting a URL inside another URL's parameter, as in a redirect target, is the one case where encoding twice is correct.)

Encode in 6 languages

// JavaScript
encodeURIComponent('café & tea');                // caf%C3%A9%20%26%20tea
new URLSearchParams({q: 'café & tea'}) + '';     // q=caf%C3%A9+%26+tea

// PHP
rawurlencode('café & tea');                      // caf%C3%A9%20%26%20tea
http_build_query(['q' => 'café & tea']);          // q=caf%C3%A9+%26+tea

# Python
from urllib.parse import quote, quote_plus
quote('café & tea', safe='')                     # caf%C3%A9%20%26%20tea

// Java
URLEncoder.encode("café & tea", StandardCharsets.UTF_8).replace("+", "%20");

// C#
Uri.EscapeDataString("café & tea");              // caf%C3%A9%20%26%20tea

# Shell
curl -G --data-urlencode "q=café & tea" https://example.com/search

Security notes

  • Decode once, then validate. Checking a still-encoded path lets %2e%2e%2f (../) slip through.
  • Validate redirect targets after decoding to prevent open redirects.
  • Always encode user input that you insert into a URL, to stop parameter injection (a value like x&admin=1).
  • Percent-encoding hides nothing. Do not treat it as encryption.

Troubleshooting checklist

  • Link breaks at & or #: a value was not encoded.
  • Link contains %2520: encoded twice.
  • Link shows https%3A%2F%2F at the start: the whole URL was encoded with the component method.
  • Spaces appear as + in a file name: a form decoder was used on a path.
  • URI malformed error: a lone % or bad UTF-8, see the decoder page.

Tools on this site

Frequently asked questions

What is URL encoding used for?

It makes sure that any text, including spaces, symbols and non-English characters, can be placed in a URL without breaking its structure.

Which characters must be URL encoded?

Everything except letters, digits and - . _ ~ . Reserved characters like & = ? # / must be encoded when they are part of a value.

Is URL encoding the same as Base64?

No. URL encoding keeps readable text readable and changes only unsafe bytes. Base64 converts binary data to a different alphabet.

What is the difference between URL encoding and HTML encoding?

URL encoding uses %XX for URLs. HTML encoding uses entities such as &amp; for web page text.

Why do I see %2520 in my URL?

The value was encoded twice: the % of %20 was itself encoded as %25.