urllib.parse

—

Updated March 13, 2026 · Modules

stdlib url parsing web

The urllib.parse module is part of Python’s standard library and provides functions for parsing URLs into components and manipulating query strings. It handles the tricky parts of URL parsing so you don’t have to write your own parsing logic.

Syntax

from urllib import parse

Key Functions

urlparse() and urlsplit()

These functions parse a URL into its components.

from urllib.parse import urlparse, urlsplit

url = "https://example.com:8080/path/to/page?key=value#section"

result = urlparse(url)
print(result)
# ParseResult(scheme='https', netloc='example.com:8080', path='/path/to/page', params='', query='key=value', fragment='section')

print(result.scheme)   # https
print(result.netloc)   # example.com:8080
print(result.path)     # /path/to_page
print(result.query)    # key=value
print(result.fragment) # section

The urlsplit() function is similar but treats the path more consistently:

result = urlsplit("https://user:pass@example.com/path?query=1")
print(result)
# SplitResult(scheme='https', netloc='user:pass@example.com', path='/path', query='query=1', fragment='')

urlencode()

This function converts a dictionary or sequence of tuples into a URL-encoded query string.

from urllib.parse import urlencode

params = {"name": "Alice Smith", "age": 30, "city": "New York"}
encoded = urlencode(params)
print(encoded)
# name=Alice+Smith&age=30&city=New+York

# For more complex encoding, use quote
from urllib.parse import urlencode, quote_plus
encoded = urlencode(params, quote_via=quote_plus)
print(encoded)
# name=Alice+Smith&age=30&city=New+York

quote() and quote_plus()

These functions URL-encode a string, replacing special characters with %XX sequences.

from urllib.parse import quote, quote_plus

# Basic usage - encodes spaces and special chars
text = "Hello World! & Friends"
print(quote(text))
# Hello%20World%21%20%26%20Friends

# quote_plus replaces spaces with + (like form encoding)
print(quote_plus(text))
# Hello+World%21+%26+Friends

# Safe characters - specify chars to not encode
print(quote("/path/to file", safe="/"))
# /path/to%20file

unquote() and unquote_plus()

These functions decode URL-encoded strings.

from urllib.parse import unquote, unquote_plus

encoded = "Hello%20World%21%20%26%20Friends"
print(unquote(encoded))
# Hello World! & Friends

encoded_plus = "Hello+World%21+%26+Friends"
print(unquote_plus(encoded_plus))
# Hello World! & Friends

parse_qs() and parse_qsl()

These functions parse a query string into a dictionary or list of tuples.

from urllib.parse import parse_qs, parse_qsl

query = "name=Alice&age=30&city=New&city=York"

# parse_qs returns a dictionary with lists as values
result = parse_qs(query)
print(result)
# {'name': ['Alice'], 'age': ['30'], 'city': ['New', 'York']}

# parse_qsl returns a list of tuples, preserving order and duplicates
result = parse_qsl(query)
print(result)
# [('name', 'Alice'), ('age', '30'), ('city', 'New'), ('city', 'York')]

# Keep blank values
result = parse_qs("key=&other=value", keep_blank_values=True)
print(result)
# {'key': [''], 'other': ['value']}

Common Patterns

Building URLs

from urllib.parse import urljoin, urlunsplit

base = "https://example.com/path/"

# urljoin handles relative paths correctly
print(urljoin(base, "page.html"))
# https://example.com/path/page.html
print(urljoin(base, "../other/page.html"))
# https://example.com/other/page.html
print(urljoin(base, "/absolute/path"))
# https://example.com/absolute/path

# urlunsplit combines components into a full URL
url = urlunsplit(("https", "example.com:8080", "/path", "key=value", "section"))
print(url)
# https://example.com:8080/path?key=value#section

Parsing URLs from strings

from urllib.parse import urlparse

# Extract domain from URL
def get_domain(url):
    parsed = urlparse(url)
    return parsed.netloc

print(get_domain("https://api.example.com/v1/users"))
# api.example.com

# Check if URL is HTTPS
def is_secure(url):
    return urlparse(url).scheme == "https"

print(is_secure("https://example.com"))  # True
print(is_secure("http://example.com"))   # False