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"] }



  • 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.

Type Aliases§