The PAC file
reference you need.

About this site

Why this page exists.

What is a PAC file?

A plain-text JavaScript file that tells browsers which proxy to use, per request.

A Proxy Auto-Configuration (PAC) file contains exactly one JavaScript function: FindProxyForURL(url, host). Browsers call this function for every outbound request. Your function inspects the URL and hostname and returns a string telling the browser what to do. PAC files were introduced by Netscape in 1996 and remain broadly supported across all major browsers and operating systems today.

Quick start

A solid production template to build from.

function FindProxyForURL(url, host) {

  // 1. Bypass proxy for plain (unqualified) hostnames
  if (isPlainHostName(host)) {
    return "DIRECT";
  }

  // 2. Bypass for internal corporate domains
  if ( dnsDomainIs(host, ".corp.internal")
    || dnsDomainIs(host, ".corp.com")) {
    return "DIRECT";
  }

  // 3. Bypass for RFC1918 private ranges — resolve once, reuse
  var ip = dnsResolve(host);
  if (ip && (
       isInNet(ip, "10.0.0.0",    "255.0.0.0")
    || isInNet(ip, "172.16.0.0",  "255.240.0.0")
    || isInNet(ip, "192.168.0.0", "255.255.0.0")
    || isInNet(ip, "127.0.0.0",   "255.0.0.0"))) {
    return "DIRECT";
  }

  // 4. Everything else: primary proxy → fallback proxy → direct
  return "PROXY proxy1.corp.com:8080; PROXY proxy2.corp.com:8080; DIRECT";
}

Return values

Strings returned by FindProxyForURL control how each request is routed.

Proxy chaining & fallback

Multiple directives in a return string create an ordered fallback chain.

When you return multiple directives separated by semicolons, the browser tries them strictly left to right, in the order written. It only moves to the next directive if the current one is unreachable or times out — it does not load-balance across them automatically.

return "PROXY primary.corp.com:8080; PROXY backup.corp.com:8080; DIRECT";
// ↑ tried first          ↑ tried if primary fails  ↑ last resort

• ①
  The browser connects to primary.corp.com:8080 first. If it responds, all traffic goes through it.
• ②
  If primary is unreachable or times out, the browser automatically retries via backup.corp.com:8080.
• ③
  DIRECT at the end means if both proxies fail, the browser will attempt a direct connection as a last resort. Omit DIRECT if you never want requests to bypass the proxy.
• ⚠
  Proxy failover adds latency — the browser must wait for a connection timeout before trying the next entry. Keep fallback chains short and use reliable primary proxies.

Compute-intensive functions

Some PAC functions trigger synchronous DNS lookups that block the browser. Know which ones to avoid.

PAC evaluation is synchronous and blocking — the browser freezes the request until FindProxyForURL returns. Functions that perform DNS resolution amplify this effect: every DNS round-trip adds tens to hundreds of milliseconds to every request.

The golden rule:

function FindProxyForURL(url, host) {

  // ✓ FAST: domain checks first — zero DNS cost
  if ( isPlainHostName(host)
    || dnsDomainIs(host, ".corp.com")
    || shExpMatch(host, "*.local")) {
    return "DIRECT";
  }

  // ✓ ONE DNS call — stored and reused below
  var ip = dnsResolve(host);
  if (!ip) { return "DIRECT"; } // ✓ guard failure case

  // ✓ FAST: isInNet receives an IP — no extra DNS
  if ( isInNet(ip, "10.0.0.0",    "255.0.0.0")
    || isInNet(ip, "192.168.0.0", "255.255.0.0")) {
    return "DIRECT";
  }

  // ✗ WRONG — triggers a second DNS lookup for the same host:
  // if (isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0")) { ... }

  return "PROXY proxy.corp.com:8080";
}

Special use cases

Advanced patterns for load balancing, geo-routing, and path-based routing.

function FindProxyForURL(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }

  var myip      = myIpAddress();          // e.g. "192.168.1.24"
  var parts     = myip.split(".");
  var lastOctet = parseInt(parts[3], 10);

  if ((lastOctet % 2) === 0) {
    return "PROXY proxy-a.corp.com:8080; PROXY proxy-b.corp.com:8080";
  } else {
    return "PROXY proxy-b.corp.com:8080; PROXY proxy-a.corp.com:8080";
  }
}

function FindProxyForURL(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }

  var proxies = [
    "PROXY proxy-0.corp.com:8080",
    "PROXY proxy-1.corp.com:8080",
    "PROXY proxy-2.corp.com:8080"
  ];

  // Simple hash: sum of char codes mod N
  var hash = 0;
  for (var i = 0; i < host.length; i++) {
    hash += host.charCodeAt(i);
  }
  return proxies[hash % proxies.length] + "; PROXY fallback.corp.com:8080";
}

function FindProxyForURL(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }

  var myip = myIpAddress();

  if (isInNet(myip, "10.10.0.0", "255.255.0.0")) {
    return "PROXY proxy-eu.corp.com:8080";   // London office
  }
  if (isInNet(myip, "10.20.0.0", "255.255.0.0")) {
    return "PROXY proxy-us.corp.com:8080";   // New York office
  }
  if (isInNet(myip, "10.30.0.0", "255.255.0.0")) {
    return "PROXY proxy-apac.corp.com:8080"; // Singapore office
  }
  return "PROXY proxy-default.corp.com:8080";
}

function FindProxyForURL(url, host) {

  // Route API traffic to a dedicated high-bandwidth proxy
  if ( shExpMatch(url, "http://api.example.com/*")
    || dnsDomainIs(host, ".api.example.com")) {
    return "PROXY api-proxy.corp.com:8080";
  }

  // Route streaming to a bypass proxy
  if ( dnsDomainIs(host, ".netflix.com")
    || dnsDomainIs(host, ".spotify.com")
    || dnsDomainIs(host, ".youtube.com")) {
    return "DIRECT"; // bypass proxy for high-bandwidth streaming
  }

  return "PROXY default.corp.com:8080";
}

Best practices

Patterns that make PAC files reliable, fast, and maintainable.

• ①
  DNS-free checks go first. Order your conditions so that isPlainHostName(), dnsDomainIs(), and shExpMatch() are evaluated before anything that triggers DNS. The majority of internal traffic matches these checks and exits early — saving DNS round-trips for the rest.
• ②
  Resolve DNS once. Assign dnsResolve(host) to a variable at the top of the function and reuse it for every isInNet() call. Calling dnsResolve() or isResolvable() multiple times for the same host multiplies your DNS cost.
• ③
  Guard DNS failures. dnsResolve() returns an empty string "" on failure, not null. Always check if (ip && ...) before passing to isInNet() — an empty string will produce incorrect matches.
• ④
  Logical operators at the start of lines. In multi-line conditions, place || and && at the beginning of each continuation line, not the end. This way every line is self-contained — you can safely copy/paste, delete, or comment out any line without worrying about whether the previous line now has a dangling operator.
• ⑤
  Always include a catch-all return. The last line of your function must unconditionally return something. If execution falls through without returning, the browser's behaviour is undefined — it may throw an error, go direct, or refuse the request entirely.
• ⑥
  Serve with the correct MIME type. The PAC file must be served as application/x-ns-proxy-autoconfig. Some clients also accept application/x-javascript-config or text/javascript, but the former is the most widely supported. An incorrect MIME type will cause clients to silently ignore the file.
• ⑦
  Keep fallback chains short. Each entry in a semicolon-separated return chain adds a full connection timeout before the browser moves to the next one. Limit yourself to two proxies plus DIRECT at most. If you need more proxies, use load balancing logic in the PAC file itself.
• ⑧
  Version your PAC files. Add a comment at the top with a version number and date. PAC files are often cached aggressively — a version comment makes it easy to verify which version a client actually loaded during debugging.
• ⑨
  Remove all alert() calls before deploying. Debug alerts break PAC evaluation in some browsers and can expose internal routing logic to end users. Use pacparser or browser DevTools for testing instead.
• ⑩
  Use IP addresses in subnet patterns. In isInNet(host, pattern, mask), pattern must always be a dotted-decimal IP — never a hostname. Hostnames in pattern can fail silently across browsers.

Security

PAC files are a high-value attack target. Understand the risks before deploying.

• 🔒
  Serve PAC files over HTTPS. The original PAC spec used plain HTTP. A man-in-the-middle attacker on the same network can intercept an HTTP PAC request and inject a malicious PAC file, silently redirecting all your traffic. Always serve PAC files from an HTTPS URL.
• 🔒
  WPAD auto-discovery is inherently risky. WPAD uses DHCP and DNS to locate your PAC file automatically. A rogue DHCP server or DNS poisoning attack can serve any machine on the network a malicious PAC URL. Disable WPAD auto-discovery in environments where you don't control the network, and configure the PAC URL explicitly.
• 🔒
  Never embed credentials in PAC files. PAC files are served as plain text and cached in the browser. Never include proxy usernames, passwords, API keys, or any other secrets in your PAC file.
• 🔒
  Restrict PAC file access. Your PAC file server should only be accessible from internal networks. A publicly accessible PAC file reveals your internal network topology, proxy addresses, and IP ranges to anyone who fetches it.
• 🔒
  HTTPS path stripping is a known limitation. For HTTPS URLs, the browser only passes the scheme, host, and port to FindProxyForURL — the path and query are stripped before PAC evaluation. Do not rely on URL path matching for security-critical routing decisions involving HTTPS traffic.
• 🔒
  PAC files can be weaponised via DNS rebinding. A malicious PAC file could call dnsResolve() on attacker-controlled domains to map your internal IP space, or use isInNet() to probe your network topology. Keep PAC evaluation sandboxed and never serve third-party PAC files.

WPAD auto-discovery

How browsers automatically find your PAC file without manual configuration.

Web Proxy Auto-Discovery (WPAD) lets browsers find the PAC file URL automatically using DHCP or DNS, eliminating the need to configure the PAC URL on every client machine. The convention is to name the file wpad.dat (instead of proxy.pac) when using WPAD.

Testing & debugging

How to validate your PAC file before deploying it to production.

# Install (macOS)
brew install pacparser

# Install (Ubuntu / Debian)
sudo apt install pacparser

# Test a PAC file against a URL
pactester -p proxy.pac -u https://www.google.com -h www.google.com

# Expected output:
# PROXY proxy.corp.com:8080

# Test multiple URLs from a file
pactester -p proxy.pac -f urls.txt

# 1. Open about:config → set network.proxy.autoconfig_url to your PAC file URL
# 2. Set network.proxy.type = 2 (use PAC file)
# 3. Open DevTools → Browser Console (not page console)
# 4. alert() calls in your PAC file appear as "PAC-alert: ..." messages
# 5. Navigate to a URL and watch the console for evaluation output

function FindProxyForURL(url, host) {
  var result = _findProxy(url, host);
  alert("PAC: " + host + " → " + result);
  return result;
}

function _findProxy(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }
  return "PROXY proxy.corp.com:8080";
}

# Open chrome://net-export/ → Start Logging → browse → Stop
# Open https://netlog-viewer.appspot.com/ → load the exported JSON
# Filter events by "PAC_RESOLVE" to see per-request PAC results

# macOS: test PAC from the command line using scutil
scutil --proxy    # shows current proxy configuration

Also try the Live Tester on this page for quick in-browser validation. It simulates all PAC helper functions and evaluates your PAC file client-side — no data is sent anywhere.

Troubleshooting

Common PAC file bugs and how to fix them.

Common examples

Real-world PAC files for the most common deployment scenarios.

function FindProxyForURL(url, host) {

  // Fast checks first — no DNS cost
  if (isPlainHostName(host)) { return "DIRECT"; }

  if ( dnsDomainIs(host, ".corp.internal")
    || dnsDomainIs(host, ".corp.com")) {
    return "DIRECT";
  }

  // One DNS call — reused for all subnet checks
  var ip = dnsResolve(host);
  if (ip && (
       isInNet(ip, "10.0.0.0",    "255.0.0.0")
    || isInNet(ip, "172.16.0.0",  "255.240.0.0")
    || isInNet(ip, "192.168.0.0", "255.255.0.0")
    || isInNet(ip, "127.0.0.0",   "255.0.0.0"))) {
    return "DIRECT";
  }

  return "PROXY proxy1.corp.com:8080; PROXY proxy2.corp.com:8080; DIRECT";
}

function FindProxyForURL(url, host) {
  if (shExpMatch(url, "http:*"))  { return "PROXY http-proxy.corp.com:8080"; }
  if (shExpMatch(url, "https:*")) { return "PROXY ssl-proxy.corp.com:8443";  }
  if (shExpMatch(url, "ftp:*"))   { return "DIRECT"; }
  return "DIRECT";
}

function FindProxyForURL(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }

  if ( weekdayRange("MON", "FRI")
    && timeRange(8, 18)) {
    return "PROXY proxy.corp.com:8080";
  }
  return "DIRECT";
}

function FindProxyForURL(url, host) {
  if (isPlainHostName(host)) { return "DIRECT"; }
  return "SOCKS5 socks.corp.com:1080; PROXY proxy.corp.com:8080; DIRECT";
}

Live tester

Paste your PAC file and evaluate it against any URL — runs entirely in your browser. Ctrl+Enter to run.