furl

library2.1.4pypypi✓ verified 29d ago

Furl is a Python library designed for simple and powerful manipulation of URLs. It provides an object-oriented interface to parse, modify, and generate URLs, allowing easy access and modification of schemes, hosts, paths, query parameters, and fragments. The current version is 2.1.4, and it generally follows an as-needed release cadence for bug fixes and minor improvements, with major versions indicating significant API changes.

http-networking serialization

pip install furl

github ↗package ↗

INSTALL

IMPORT

SIG · FURL

furl

http-networkingpythonv2.1.4

Install

1.7s avg

Import

38ms

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 v2.1.4 · 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.040s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.036s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

furl

✓ from furl import furl

This quickstart demonstrates how to create a `furl` object, access and modify its various components (scheme, host, path, query, fragment), and use methods like `join()` to combine URLs.

from furl import furl # Create a URL object f = furl("https://www.example.com/path/to/resource?param1=value1&param2=value2#fragment") print(f"Original URL: {f.url}") # Access components print(f"Scheme: {f.scheme}") print(f"Host: {f.host}") print(f"Path: {f.path}") print(f"Query parameters: {f.query.params}") print(f"Fragment: {f.fragment}") # Modify components f.scheme = "http" f.host = "api.example.org" f.path /= "v1" # Append path segment f.query.add("apikey", "YOUR_API_KEY") # Add a query parameter f.remove(fragment=True) # Remove fragment print(f"Modified URL: {f.url}") # Join URLs base = furl("http://base.com/foo") relative = furl("/bar?baz=qux") joined = base.join(relative) print(f"Joined URL: {joined.url}")

Debug

Known issues

breakingAs of v2.1.4, furl dropped support for all Python versions prior to Python 3.8, which are now long past EOL.

fix

Upgrade your Python environment to 3.8 or newer, or pin furl to a version less than 2.1.4.

affects: >=2.1.4

breakingThe division operator (`/`) for `furl` and `Path` objects no longer modifies the instance in-place. It now returns a new instance, mirroring `Pathlib`'s behavior.

fix

Assign the result of the operation back to the variable (e.g., `f = f / 'segment'`) or use the in-place assignment operator (`f /= 'segment'`).

affects: >=2.0.0

gotchaDue to changes in Python 3.9's `urllib.parse.urljoin()`, the `furl.join()` method's behavior for specific relative URLs (e.g., starting with a scheme-like string such as 'foo:1') will differ on Python 3.9+ compared to older Python versions. On Python < 3.9, `furl('wss://slrp.com/').join('foo:1')` returned `'wss://slrp.com/foo:1'`, but on Python >= 3.9, it returns `'foo:1'`.

fix

Be aware of this behavior change when using `furl.join()` with scheme-like relative URLs on Python 3.9 and newer. Test your URL joining logic if it relies on specific edge cases.

affects: >=2.1.2

gotchaSupport for semicolon (`;`) as a query delimiter has been dropped in alignment with `urllib.parse`'s behavior. URLs using semicolons as delimiters in their query string will now be parsed differently.

fix

Ensure your applications rely on ampersands (`&`) as the standard query delimiter. If consuming URLs with semicolon delimiters, consider pre-processing or adapting parsing logic to convert them to ampersands if needed.

affects: >=2.1.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'furl'

The 'furl' library is not installed in the Python environment being used, or the environment is not correctly configured.

fix

Install the 'furl' library using pip: `pip install furl` or `python -m pip install furl`.

ValueError: Invalid host '<host_string>'

This error occurs when an invalid string is assigned to the `host` attribute of a `furl` object, often due to characters that are not permitted in a URL host or incorrect escaping.

fix

Ensure the host string contains only valid characters (alphanumeric, hyphens, periods) and does not include scheme, username, password, or port information. If assigning a full netloc, it should be parsed correctly, or set individual components like `f.host`, `f.port`, etc. For example, `f.host = 'example.com'` instead of `f.host = 'user:pass@example.com'`.

ValueError: Invalid port: '<port_string>'

You are attempting to set an invalid value for the `port` attribute, which expects an integer or `None`, but received a non-numeric or out-of-range value.

fix

Assign an integer between 1 and 65535 (inclusive) or `None` to the `port` attribute. For example: `f.port = 8080` or `f.port = None`.

AttributeError: Path.isabsolute is True and read-only for URLs with a netloc

This error arises when you try to modify the `isabsolute` attribute of a `furl.path` object when the `furl` instance already has a `netloc` (host, port, username, or password). URL paths must be absolute (start with '/') if a netloc is present to separate from it.

fix

Do not directly set `f.path.isabsolute = False` if the `furl` object has a `netloc`. If you need a relative path with a netloc, consider if your URL structure is logically correct. If you want a relative path, ensure the `furl` object does not have a `netloc` set or construct the relative path separately. For example: `f = furl('/relative/path')` or clear the netloc first: `f.netloc = ''` before modifying `f.path.isabsolute`.

furl('127.0.0.1:8080/a/b') results in furl('8080/a/b') or incorrect parsing

When a URL without an explicit scheme (like 'http://') is passed to `furl`, such as just an IP address and port, `furl` might misinterpret the host and path components, treating the entire string up to the first '/' as a path rather than a host:port.

fix

Always provide a scheme for absolute URLs to ensure correct parsing of host and port. For example: `furl('http://127.0.0.1:8080/a/b')` or `furl('//127.0.0.1:8080/a/b')` for a protocol-relative URL.

Upgrade

Version history

2.1.4latest on PyPI · released Mar 9, 2025

Audit

Dependencies

orderedmultidictrequiredRequired for internal ordered dictionary-like structures for query parameters.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/gruns/furl ↗

packagehttps://pypi.org/project/furl/ ↗