Registry / http-networking / url-normalize

url-normalize

library3.0.0pypypi✓ verified 26d ago

URL Normalize is a Python library (current version 2.2.1) designed for standardizing and normalizing URLs, including support for internationalized domain names (IDN). It handles various aspects like scheme and host lowercasing, percent-encoding, path segment collapsing, and configurable default schemes and query parameter filtering. It is actively maintained with regular releases.

http-networking

pip install url-normalize

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · URL-NORMALIZE

url-normalize

http-networkingpythonv3.0.0

Install

1.6s avg

Import

32ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.034s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.030s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

url_normalize

✓ from url_normalize import url_normalize

✗ import url_normalize

The primary normalization function `url_normalize` is typically imported directly from the package, not accessed as an attribute of the top-level `url_normalize` package.

Demonstrates basic URL normalization and how to normalize a path by providing a default domain and scheme.

from url_normalize import url_normalize # Basic normalization normalized_url = url_normalize("HTTP://www.Example.com:80/a/../b?c=2&c=1") print(f"Normalized URL: {normalized_url}") # Expected: https://www.example.com/b?c=1&c=2 # Normalizing a path with a default domain and scheme normalized_path = url_normalize("/foo/bar", default_domain="example.com", default_scheme="http") print(f"Normalized path with domain: {normalized_path}") # Expected: http://example.com/foo/bar

Debug

Known issues

breakingThe default scheme for URLs without one has changed from 'http' to 'https'.

fix

If your application relies on 'http' as the default, explicitly set `default_scheme='http'` when calling `url_normalize`.

affects: 2.0.0 and later

breakingThe minimum required Python version has been updated to 3.8.

fix

Upgrade your Python environment to 3.8 or newer. For older Python versions, use `url-normalize` versions prior to 2.0.0.

affects: 2.0.0 and later

breakingIDNA handling has been migrated to use IDNA 2008 with UTS46 processing, requiring the `idna` package.

fix

Ensure the `idna` package is installed (`pip install idna`). Review IDN-specific normalization behavior as it might differ slightly from previous versions.

affects: 2.0.0 and later

breakingThe `sort_query_params` option has been removed as it was deemed incorrect in its previous implementation.

fix

Remove the `sort_query_params` argument from your `url_normalize` calls. Query parameters are now sorted by default. If specific custom sorting is needed, it must be applied manually before normalization.

affects: 2.0.0 and later

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'url_normalize'

The `url-normalize` package has not been installed in your Python environment.

fix

Install the package using pip: `pip install url-normalize`

TypeError: url must be str, not NoneType

The `url_normalize` function received a non-string argument (e.g., `None`, an integer, or a list) instead of a URL string.

fix

Ensure the argument passed to `url_normalize` is always a string. Example: `from url_normalize import url_normalize; url_normalize('http://example.com')`

ValueError: default_scheme must not contain a colon

The `default_scheme` parameter was provided with a colon (e.g., 'http://') instead of just the scheme name (e.g., 'http').

fix

Provide only the scheme name for the `default_scheme` parameter. Example: `from url_normalize import url_normalize; url_normalize('//example.com', default_scheme='https')`

idna.core.IDNAError: Invalid character

The URL contains an invalid Internationalized Domain Name (IDN) that cannot be properly encoded according to IDNA rules, often due to invalid characters or formatting.

fix

Ensure the IDN part of the URL is a valid and properly formatted Unicode string that can be encoded by the `idna` codec. Example: `from url_normalize import url_normalize; url_normalize('http://xn--fsk.example.com')`

Upgrade

Version history

3.0.0latest on PyPI · released Apr 25, 2026

Audit

Dependencies

idnarequiredRequired for IDNA 2008 and UTS46 processing for internationalized domain names.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/niksite/url-normalize ↗

packagehttps://pypi.org/project/url-normalize/ ↗

changeloghttps://github.com/niksite/url-normalize/blob/master/CHANGELOG.md ↗