{"id":2040,"library":"furl","title":"Furl","description":"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.","status":"active","version":"2.1.4","language":"python","source_language":"en","source_url":"https://github.com/gruns/furl","tags":["url","parsing","manipulation","networking"],"install":[{"cmd":"pip install furl","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for internal ordered dictionary-like structures for query parameters.","package":"orderedmultidict","optional":false}],"imports":[{"symbol":"furl","correct":"from furl import furl"}],"quickstart":{"code":"from furl import furl\n\n# Create a URL object\nf = furl(\"https://www.example.com/path/to/resource?param1=value1&param2=value2#fragment\")\nprint(f\"Original URL: {f.url}\")\n\n# Access components\nprint(f\"Scheme: {f.scheme}\")\nprint(f\"Host: {f.host}\")\nprint(f\"Path: {f.path}\")\nprint(f\"Query parameters: {f.query.params}\")\nprint(f\"Fragment: {f.fragment}\")\n\n# Modify components\nf.scheme = \"http\"\nf.host = \"api.example.org\"\nf.path /= \"v1\" # Append path segment\nf.query.add(\"apikey\", \"YOUR_API_KEY\") # Add a query parameter\nf.remove(fragment=True) # Remove fragment\n\nprint(f\"Modified URL: {f.url}\")\n\n# Join URLs\nbase = furl(\"http://base.com/foo\")\nrelative = furl(\"/bar?baz=qux\")\njoined = base.join(relative)\nprint(f\"Joined URL: {joined.url}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or newer, or pin furl to a version less than 2.1.4.","message":"As of v2.1.4, furl dropped support for all Python versions prior to Python 3.8, which are now long past EOL.","severity":"breaking","affected_versions":">=2.1.4"},{"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'`).","message":"The division operator (`/`) for `furl` and `Path` objects no longer modifies the instance in-place. It now returns a new instance, mirroring `Pathlib`'s behavior.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Due 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'`.","severity":"gotcha","affected_versions":">=2.1.2"},{"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.","message":"Support 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.","severity":"gotcha","affected_versions":">=2.1.2"}],"env_vars":null,"search_vec":"'2.1.4':45 'access':30 'allow':28 'api':67 'as-need':51 'bug':57 'cadenc':55 'chang':68 'current':42 'design':7 'easi':29 'fix':58 'follow':49 'fragment':40 'furl':1,2 'general':48 'generat':26 'host':35 'improv':61 'indic':65 'interfac':21 'librari':6 'major':63 'manipul':12,71 'minor':60 'modif':32 'modifi':24 'need':53 'network':72 'object':19 'object-ori':18 'orient':20 'paramet':38 'pars':23,70 'path':36 'power':11 'provid':16 'python':5 'queri':37 'releas':54 'scheme':34 'signific':66 'simpl':9 'url':14,27,69 'version':43,64","created_at":"2026-04-09T18:40:56.958276+00:00","updated_at":"2026-04-16T15:12:35.429755+00:00","problems":[{"fix":"Install the 'furl' library using pip: `pip install furl` or `python -m pip install furl`.","cause":"The 'furl' library is not installed in the Python environment being used, or the environment is not correctly configured.","error":"ModuleNotFoundError: No module named 'furl'"},{"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'`.","cause":"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.","error":"ValueError: Invalid host '<host_string>'"},{"fix":"Assign an integer between 1 and 65535 (inclusive) or `None` to the `port` attribute. For example: `f.port = 8080` or `f.port = None`.","cause":"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.","error":"ValueError: Invalid port: '<port_string>'"},{"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`.","cause":"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.","error":"AttributeError: Path.isabsolute is True and read-only for URLs with a netloc"},{"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.","cause":"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.","error":"furl('127.0.0.1:8080/a/b') results in furl('8080/a/b') or incorrect parsing"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/gruns/furl","docs":null,"changelog":null,"pypi":"https://pypi.org/project/furl/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}