How it works
URL components have different escaping rules. urlencode builds a query string from key-value data; quote can encode an individual path segment. Encoding is not encryption and does not hide sensitive values.
A query value containing an ampersand must not become a new parameter. Using library functions avoids the mistakes caused by simply joining unescaped user strings with & and =.
Limitations and practical choices
For one path segment, quote(value, safe="") also escapes slashes that should be treated as data. Do not blindly quote an entire already-structured URL.
Parsing or encoding a URL does not validate its destination. Apply separate scheme and host rules where a program is allowed to fetch only certain resources.
Try it yourself
Build a query with a search phrase containing both spaces and an ampersand. Parse it back and verify that it is still one value.
Syntax
from urllib.parse import urlencode
query = urlencode({"q": "Python examples"})Examples
Encode a query
Keep punctuation inside its intended parameter.
from urllib.parse import urlencode
query = urlencode({"q": "cats & dogs", "page": 2})
print(query)- urlencode encodes spaces as plus signs in this query format and the data ampersand as %26.
- The unescaped ampersand between q and page is the parameter separator. The encoded one remains part of q’s value.
- Use this when constructing a search link from structured values rather than concatenating raw user input.
- Expected output: q=cats+%26+dogs&page=2
Preserve multiple values
Represent repeated parameters explicitly.
from urllib.parse import urlencode, parse_qs
query = urlencode({"tag": ["python", "web"]}, doseq=True)
print(query)
print(parse_qs(query))- doseq=True expands the list into repeated tag parameters. parse_qs reconstructs a dictionary whose values are lists.
- Without doseq, the list would be treated as a single value representation rather than the intended repeated fields.
- Repeated query parameters can represent multiple selected filters; the receiving application must support that convention.
- Expected output: tag=python&tag=web {'tag': ['python', 'web']}
Encode a single path segment
Prevent a slash in a value from creating another path level.
from urllib.parse import quote, unquote
segment = "reports/July notes"
encoded = quote(segment, safe="")
print(encoded)
print(unquote(encoded))- safe="" removes the usual slash exception so the entire input is treated as one segment. Spaces become %20.
- unquote demonstrates the round trip. Whether an encoded slash is allowed depends on the server and route design.
- Use an identifier instead when a service forbids encoded slashes; encoding does not override server-side path rules.
- Expected output: reports%2FJuly%20notes reports/July notes
Best practices
- For one path segment, quote(value, safe="") also escapes slashes that should be treated as data. Do not blindly quote an entire already-structured URL.
- Parsing or encoding a URL does not validate its destination. Apply separate scheme and host rules where a program is allowed to fetch only certain resources.
Runtime & versions
Python interpreter. Feature availability depends on the language and runtime version used by your project; consult the official reference below.
Python language reference