Introduction

In Python, the normal way to URL-encode a query string is urllib.parse.urlencode. It handles the percent-encoding rules for query parameters so you do not have to manually replace spaces, ampersands, or non-ASCII characters yourself.

Use urllib.parse.urlencode

The basic pattern looks like this:

1from urllib.parse import urlencode
2
3params = {
4    "q": "python urllib",
5    "page": 2,
6    "sort": "newest first",
7}
8
9query_string = urlencode(params)
10print(query_string)

Output:

q=python+urllib&page=2&sort=newest+first

This is exactly what you want for standard query-string construction. Spaces become + in the query component, and reserved characters are safely encoded.

Build a full URL from the encoded query string

Once you have the encoded query string, append it to the base URL:

1from urllib.parse import urlencode
2
3base_url = "https://example.com/search"
4params = {
5    "q": "machine learning",
6    "lang": "en",
7}
8
9url = f"{base_url}?{urlencode(params)}"
10print(url)

That gives you a properly encoded URL without manual string escaping.

Handle repeated parameters with doseq=True

If a parameter can have multiple values, pass a list and enable doseq=True:

1from urllib.parse import urlencode
2
3params = {
4    "tag": ["python", "web", "api"],
5    "page": 1,
6}
7
8query_string = urlencode(params, doseq=True)
9print(query_string)

Output:

tag=python&tag=web&tag=api&page=1

Without doseq=True, the list itself would be stringified in a way that is usually not what web frameworks expect.

Know the difference between quote and urlencode

urlencode is for whole query parameter mappings. quote is for encoding a single string fragment.

Example with quote:

1from urllib.parse import quote
2
3value = "a/b test"
4print(quote(value))

If you already have key-value parameters, urlencode is the higher-level and more appropriate tool:

from urllib.parse import urlencode

print(urlencode({"path": "a/b test"}))

Using the right function matters because different parts of a URL have different encoding rules.

Character encoding and non-ASCII text

urlencode handles Unicode values too:

1from urllib.parse import urlencode
2
3params = {
4    "city": "Montréal",
5    "term": "café",
6}
7
8print(urlencode(params))

That percent-encodes the non-ASCII bytes safely for transport in the URL.

In most modern Python code, you do not need to hand-manage this encoding step unless you are interfacing with something extremely unusual.

If you need different space-handling behavior, remember that standard query encoding uses + for spaces. That is normal for query strings. If you are encoding a URL path segment instead, use the path-oriented quoting tools instead of forcing query-string rules onto the wrong part of the URL.

When a request library can do it for you

If you are making HTTP requests, libraries such as requests can build the query string automatically:

1import requests
2
3response = requests.get(
4    "https://example.com/search",
5    params={"q": "python urllib", "page": 2},
6)
7
8print(response.request.url)

That is often cleaner than building the URL manually when your real goal is to make the request rather than manipulate the string yourself.

Common Pitfalls

The biggest mistake is manually replacing spaces or special characters instead of using urlencode. Manual escaping is error-prone and easy to get wrong.

Another common issue is forgetting doseq=True when a parameter has multiple values.

People also confuse query-string encoding with path encoding. urlencode is for parameter mappings, not for arbitrary full-URL manipulation.

Finally, do not double-encode values. If a parameter string is already encoded, passing it through urlencode again can produce incorrect results.

Summary

• Use urllib.parse.urlencode for standard Python query-string encoding.
• Append the encoded string to the base URL when building URLs manually.
• Use doseq=True for repeated parameters stored in lists.
• Prefer quote only for single string fragments, not whole parameter dictionaries.
• Let higher-level HTTP libraries handle query-string encoding when they already support it.