The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


HTTP::Client - Class for making HTTP requests


  use HTTP::Client;
  my $client  = HTTP::Client->new();
  my $site    = $client->get("");
  my @headers = $client->response_headers;
  my $agent   = $client->agent;
  print $agent . "\n";
  print $headers[$_] . "\n" foreach (0..$#headers);
  print $site;


HTTP::Client is a class for creating clients, that does not require LWP. It is aimed at speed. It can send HTTP Request headers, get HTTP response headers and get documents.



This is the constructor for HTTP::Client. It can be called like this:

   my $client = HTTP::Client->new;

or this:

   my $client = new HTTP::Client ();

it can take the useragent string as an argument like this:

   my $client = HTTP::Client->new("Bot/1.0");

If the useragent is supplied in the constructor, but then supplied in the agent() method, the constructor will be authoritative. In other words, you can only override the already specified client name by using only agent methods, and not the constructor. (This is actually a bug.)


get gets a page on the web. It can only do http pages for now. The URI (URL) to get is the only argument it takes. It returns the body of the site if successful (The HTTP status code is "200 OK", or the other HTTP status code if it is not equal to that. For example:

   my $site = $client->get("");
   print $site . "\n"; 

prints the source of or the status code if it could not find it. It will append a trailing slash to the URL if it doesn't end in one.


response_headers returns an array of all the response headers sent by the server. Currently, to loop through the array, you must use this construct:

 my $site = $client->get("");
 my @headers = $client->response_headers;
 foreach (0..$#headers) {
    print $headers[$_] . "\n";

this is a big bug.


agent sets the current User-Agent header, thus renaming the current client. If the agent was specified in the constructor, even using this method will not override the one specified in the constructor. So, you can only override your useragent with multiple agent()s, not with the constructor and then agent()s. For example:

 my $client = HTTP::Client->new("Bot/1.0");
 my $site = $client->get("");
 $client->agent("NewBot/1.0"); #Wrong! agent is still "Bot/1.0"

is wrong but this:

 my $client = HTTP::Client->new;
 my $site = $client->get("");
 $client->agent("NewBot/1.0"); #Right! useragent is NewBot/1.0!
 $client->agent("NewNewBot/1.0"); #Right! useragent is now NewNewBot/1.0!

is right and changes the useragent after the second call.


from sets the From header, which should be an email address of the person/machine that is sending the request. If the from was specified in the constructor, just like the agent method, using this method will not override the setting in the constructor. Therefore, you can only override from headers by using multiple from() methods, not by using the constructor and then from methods. For example:

 my $client = HTTP::Client->new("Bot/1.1", "nightcat\");
 my $site = $client->get("");
 $client->from("au\@th.or"); #Wrong! From is still!

doesn't work, but this:

 my $client = HTTP::Client->new;
 my $site = $client->get("");
 $client->from("nightcat\"); #Right! From is!
 $client->from("au\@th.or"); #Right! From is now au@th.or!

does. Note that you have to escape the at sign (@) in the address if you are using double quotes, because otherwise it will be interpreted as an array.


status_message returns the HTTP status message sent by the server. It returns it in the full form, e.g. "200 OK" or "404 Not Found". For example:

 my $site = $client->get("");
 print $client->status_message;

prints "200 OK". Note that if here, and anywhere else when getting a site, if a bad hostname is supplies, the program will die with the error "Can't get (url to get); may be a result of a bad hostname: (error message in $!)"


returns the value of the Server header sent by the server.


returns the Content-Type header sent by the server.


returns the Last-Modified header sent by the server.


returns the protocol sent by the server. (Usually something like "HTTP/1.1"


returns the Content-Encoding header sent by the server.


returns the Content-Length header sent by the server.


returns the Warning header sent be the server.


returns the Title header sent by the server.

Note: This is no longer part of the HTTP specification.


returns the Date header returned by the server.


returns the Host header returned by the server.


a real world example for getting documents would be:

 use HTTP::Client;
 my $client = HTTP::Client->new("GetBot/1.0");
 my $url = shift || <STDIN>;
 my $site = $client->get($url);
 print "\n" . $client->agent . " got $url successfully.";
 print "\n\nHeaders Recieved:\n";
 my @headers = $client->response_headers;
 print "$headers[$_]\n" foreach (0..$#headers);
 print "\nBody of document:\n\n";
 print $site . "\n\n";

SEE ALSO - a review of CPAN modules for making HTTP requests.

In short, you should consider one of the following modules: HTTP::Tiny, LWP::UserAgent, Furl, Mojo::UserAgent, LWP::Curl, Net::Curl.



As of 1.52, this module is now maintained by Neil Bowers <>.

HTTP::Client was written by Lincoln Ombelets <>


Copyright (C) 2005-2012 Lincoln Ombelets.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.