URL Encoding Passwords and Special Characters

When a password contains characters like @, /, ?, or #, embedding it directly into a URL breaks the URL structure. The classic example is a database connection string: postgresql://user:p@ss@host/db — the parser reads the first @ as the user-info separator and gets confused by the rest.

The fix is to URL encode the password before putting it in the URL. Every special character gets replaced with its percent-code, and the URL parser sees the whole thing as a single opaque value.

Characters in Passwords That Break URLs

These characters have reserved meanings in URL syntax and must be encoded when they appear in credentials:

Character	Problem in URLs	Encoded As
@	Separates user info from host	%40
:	Separates username from password	%3A
/	Separates path segments	%2F
?	Starts query string	%3F
#	Starts fragment	%23
&	Separates query params	%26
+	Decoded as space in form encoding	%2B
Space	Invalid in URLs	%20

Encoding Passwords in Database Connection Strings

Most database connection strings follow the format driver://user:password@host:port/database. If the password contains @ or :, the parser misreads the string.

Example password: p@ss:w0rd!

# Broken:
postgresql://admin:p@ss:[email protected]/mydb

# Fixed (password URL encoded):
postgresql://admin:p%40ss%[email protected]/mydb

In Python, encode the password before building the URL:

from urllib.parse import quote_plus
password = quote_plus('p@ss:w0rd!')
# 'p%40ss%3Aw0rd%21'
url = f'postgresql://admin:{password}@db.example.com/mydb'

Sell Custom Apparel — We Handle Printing & Free Shipping

Encoding Passwords for HTTP Basic Auth

HTTP Basic Auth credentials are passed in the Authorization header as a Base64-encoded username:password string — not as a URL. So for the header itself, you don't need to percent-encode the password.

However, if you're embedding Basic Auth credentials directly in a URL (the https://user:[email protected] format), the password must be percent-encoded because it's in a URL context.

# Header-based Basic Auth (no URL encoding needed):
Authorization: Basic base64(username:password)

# URL-embedded Basic Auth (password must be URL encoded):
https://admin:p%[email protected]/endpoint

Note: most browsers strip credentials from URLs for security reasons. Use the Authorization header instead for API calls.

How to URL Encode a Password — Step by Step

The safest approach is to encode only the password (and username if it contains special characters), not the whole URL:

1. Copy your password — just the password, not the connection string.
2. Paste it into the Mongoose URL Encoder.
3. Click Encode — every special character becomes a percent-code.
4. Use the encoded password in your connection string or URL.

In code, use encodeURIComponent(password) in JavaScript, urllib.parse.quote(password, safe='') in Python, or Uri.EscapeDataString(password) in C# — all encode everything including @ and :.

Frequently Asked Questions

Do I need to URL encode my username too?

Only if it contains special characters. Most usernames are safe ASCII. If your username contains @, /, or other reserved characters, encode it using the same method as the password.

My database library handles connection strings differently — do I still need to encode?

Check your library's documentation. Some libraries (like SQLAlchemy in Python) let you pass credentials separately from the host so you don't need to URL encode. Others require the full connection string and do need encoding.

What if I encode a password that's already stored URL-encoded in an env file?

Double-encoding is a common bug. If your .env file stores the plain password and your code encodes it at runtime, that's correct. If your .env file stores the encoded password and your code encodes it again, the percent signs themselves get encoded (%25), and authentication fails.

Can I store URL-encoded passwords in environment variables?

Yes. Store the encoded version and use it directly in connection strings without re-encoding. Or store the plain password and encode it in code at startup. Just be consistent so it doesn't get double-encoded.