URI::Fast - A fast(er) URI parser


version 0.10


  use URI::Fast qw(uri);

  my $uri = uri '';

  if ($uri->scheme =~ /http(s)?/) {
    my @path = $uri->path;
    my $a = $uri->param('a');
    my $b = $uri->param('b');

  if ($uri->path =~ /\/login/ && $uri->scheme ne 'https') {
    $uri->param('upgraded', 1);


URI::Fast is a faster alternative to URI. It is written in C and provides basic parsing and modification of a URI.

URI is an excellent module; it is battle-tested, robust, and handles many edge cases. As a result, it is rather slower than it would otherwise be for more trivial cases, such as inspecting the path or updating a single query parameter.



Accepts a URI string, minimally parses it, and returns a URI::Fast object.


Unless otherwise specified, all attributes serve as full accessors, allowing the URI segment to be both retrieved and modified.


Defaults to file if not present in the URI string.


The authorization section is composed of the username, password, host name, and port number:

Setting this field may be done with a string (see the note below about "ENCODING") or a hash reference of individual field names (usr, pwd, host, and sport). In both cases, the existing values are completely replaced by the new values and any values not present are deleted.


The username segment of the authorization string. Updating this value alters "auth".


The password segment of the authorization string. Updating this value alters "auth".


The host name segment of the authorization string. May be a domain string or an IP address. Updating this value alters "auth".


The port number segment of the authorization string. Updating this value alters "auth".


In scalar context, returns the entire path string. In list context, returns a list of path segments, split by /.

The path may also be updated using either a string or an array ref of segments:

  $uri->path(['foo', 'bar']);


The complete query string. Does not include the leading ?.


Does a fast scan of the query string and returns a list of unique parameter names that appear in the query string.


Scans the query string and returns a hash ref of key/value pairs. Values are returned as an array ref, as keys may appear multiple times.


Gets or sets a parameter value. Setting a parameter value will replace existing values completely; the "query" string will also be updated. Setting a parameter to undef deletes the parameter from the URI.

  $uri->param('foo', ['bar', 'baz']);
  $uri->param('fnord', 'slack');

  my $value_scalar    = $uri->param('fnord'); # fnord appears once
  my $value_array_ref = $uri->param('foo');   # foo appears twice
  my @value_list      = $uri->param('foo');   # list context always yields a list

  # Delete 'foo'
  $uri->param('foo', undef);


The fragment section of the URI, excluding the leading #.


URI::Fast tries to do the right thing in most cases with regard to reserved and non-ASCII characters. URI::Fast will fully encode reserved and non-ASCII characters when setting individual values. However, the "right thing" is a bit ambiguous when it comes to setting compound fields like "auth", "path", and "query".

When setting these fields with a string value, reserved characters are expected to be present, and are therefore accepted as-is. However, any non-ASCII characters will be percent-encoded (since they are unambiguous and there is no risk of double-encoding them).

  print $uri->auth; # ""

On the other hand, when setting these fields with a reference value, each field is fully percent-encoded:

  $uri->auth({usr => 'some one', host => ''});
  print $uri->auth; # ""

The same goes for return values. For compound fields returning a string, non-ASCII characters are decoded but reserved characters are not. When returning a list or reference of the deconstructed field, individual values are decoded of both reserved and non-ASCII characters.


Percent-encodes a string for use in a URI. By default, both reserved and UTF-8 chars (! * ' ( ) ; : @ & = + $ , / ? # [ ] %) are encoded.

A second (optional) parameter provides a string containing any characters the caller does not wish to be decoded. An empty string will result in the default behavior described above.

For example, to encode all characters in a query-like string except for those used by the query:

  my $encoded = URI::Fast::encode($some_string, '?&=');


Decodes a percent-encoded string.

  my $decoded = URI::Fast::decode($some_string);


See URI::Fast::Benchmarks.



The de facto standard.


Written in C++ and purportedly very fast, but appears to only support Linux.


Thanks to ZipRecruiter for encouraging their employees to contribute back to the open source ecosystem. Without their dedication to quality software development this distribution would not exist.


Jeff Ober <>


This software is copyright (c) 2018 by Jeff Ober.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.