A tiny node.js module for retrieving a request's IP address.
Latest commit e33b450 Jan 28, 2016 @pbojinov update readme



A tiny Node.js module for retrieving a request's IP address.

Coverage Status


npm install request-ip --save

Getting Started

var requestIp = require('request-ip');

// inside middleware handler
var ipMiddleware = function(req, res, next) {
    var clientIp = requestIp.getClientIp(req); 

// on localhost you'll see if you're using IPv4 
// or ::1, ::ffff: if you're using IPv6

As Connect Middleware

var requestIp = require('request-ip');

app.use(function(req, res) {
    var ip = req.clientIp;

To see a full working code for the middleware, check out the examples folder.

The connect-middleware also supports retrieving the ip address under a custom attribute name, which also works as a container for any future settings.

How It Works

It looks for specific headers in the request and falls back to some defaults if they do not exist.

The following is the order we use to determine the user ip from the request.

  1. X-Client-IP
  2. X-Forwarded-For header may return multiple IP addresses in the format: "client IP, proxy 1 IP, proxy 2 IP", so we take the the first one.
  3. X-Real-IP (nginx proxy/FastCGI)
  4. X-Cluster-Client-IP (Rackspace LB, Riverbed Stingray)
  5. Permuations of #2 such as: X-Forwarded, Forwarded-For and Forwarded
  6. req.connection.remoteAddress
  7. req.socket.remoteAddress
  8. req.connection.socket.remoteAddress
  9. req.info.remoteAddress

If cannot find an IP address, it will return null.

Samples Use Cases

  • Getting a user's IP for geolocation.



Running the Tests

Make sure you have the necessary dev dependencies needed to run the tests:

npm install

Run the integration tests

npm test

Release Notes

See the wonderful changelog

To easily generate a new changelog, install github-changelog-generator then run npm run changelog.


Thanks to @osherx for adding the connect-middleware.


The MIT License (MIT) - 2016