Crate url

source ·
Expand description

rust-url is an implementation of the URL Standard for the Rust programming language.

URL parsing and data structures

First, URL parsing may fail for various reasons and therefore returns a Result.

use url::{Url, ParseError};

assert!(Url::parse("http://[:::1]") == Err(ParseError::InvalidIpv6Address))

Let’s parse a valid URL and look at its components.

use url::{Url, Host, Position};
let issue_list_url = Url::parse(

assert!(issue_list_url.scheme() == "https");
assert!(issue_list_url.username() == "");
assert!(issue_list_url.password() == None);
assert!(issue_list_url.host_str() == Some(""));
assert!( == Some(Host::Domain("")));
assert!(issue_list_url.port() == None);
assert!(issue_list_url.path() == "/rust-lang/rust/issues");
assert!(issue_list_url.path_segments().map(|c| c.collect::<Vec<_>>()) ==
        Some(vec!["rust-lang", "rust", "issues"]));
assert!(issue_list_url.query() == Some("labels=E-easy&state=open"));
assert!(&issue_list_url[Position::BeforePath..] == "/rust-lang/rust/issues?labels=E-easy&state=open");
assert!(issue_list_url.fragment() == None);

Some URLs are said to be cannot-be-a-base: they don’t have a username, password, host, or port, and their “path” is an arbitrary string rather than slash-separated segments:

use url::Url;

let data_url = Url::parse("data:text/plain,Hello?World#")?;

assert!(data_url.scheme() == "data");
assert!(data_url.path() == "text/plain,Hello");
assert!(data_url.query() == Some("World"));
assert!(data_url.fragment() == Some(""));


Enable the serde feature to include Deserialize and Serialize implementations for url::Url.

Base URL

Many contexts allow URL references that can be relative to a base URL:

<link rel="stylesheet" href="../main.css">

Since parsed URLs are absolute, giving a base is required for parsing relative URLs:

use url::{Url, ParseError};

assert!(Url::parse("../main.css") == Err(ParseError::RelativeUrlWithoutBase))

Use the join method on an Url to use it as a base URL:

use url::Url;

let this_document = Url::parse("")?;
let css_url = this_document.join("../main.css")?;
assert_eq!(css_url.as_str(), "");

Feature: serde

If you enable the serde feature, Url will implement serde::Serialize and serde::Deserialize. See serde documentation for more information.

url = { version = "2", features = ["serde"] }

Feature: debugger_visualizer

If you enable the debugger_visualizer feature, the url crate will include a natvis file for Visual Studio that allows you to view Url objects in the debugger.

This feature requires Rust 1.71 or later.

url = { version = "2", features = ["debugger_visualizer"] }



host 🔒
origin 🔒
parser 🔒
slicing 🔒


Opaque identifier for URLs that have file or other schemes
Full configuration for the URL parser.
Exposes methods to manipulate the path of an URL that is not cannot-be-base.
A parsed URL record.
Implementation detail of Url::query_pairs_mut. Typically not used directly.


The host name of an URL.
The origin of an URL
Errors that can occur during parsing.
Indicates a position within a URL based on its components.
Non-fatal syntax violations that can occur during parsing.


RangeArg 🔒


Type Definitions