Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gotScraping
✓ import { gotScraping } from 'got-scraping';
✗ const { gotScraping } = require('got-scraping');
The package is ESM-only since v4. For compatibility with CommonJS modules, use a dynamic import: `gotScraping ??= (await import('got-scraping')).gotScraping;`
HeaderGeneratorOptions
✓ import type { HeaderGeneratorOptions } from 'got-scraping';
Type definition for configuring `headerGeneratorOptions` when customizing browser-like headers.
getAgents
✓ import { getAgents } from 'got-scraping';
Exports a function to retrieve the internal HTTP/HTTPS agents used by `got-scraping`, which can be useful for advanced agent management or debugging purposes.
Demonstrates a basic GET request using `gotScraping` with proxy support and custom header generation options, showing how to fetch and log response data.
import { gotScraping } from 'got-scraping';
async function fetchExampleData() {
try {
const response = await gotScraping.get({
url: 'https://httpbin.org/headers', // A simple endpoint to inspect request headers
proxyUrl: process.env.PROXY_URL ?? 'http://username:password@proxy.example.com:8000',
useHeaderGenerator: true,
headerGeneratorOptions: {
browsers: [
{ name: 'chrome', minVersion: 90, maxVersion: 99 }
],
devices: ['desktop'],
locales: ['en-US', 'de-DE'],
operatingSystems: ['windows', 'macos']
},
// Standard Got options are also available
timeout: { request: 30000 }, // 30-second total request timeout
retry: { limit: 2, methods: ['GET'] }, // Retry GET requests up to 2 times
headers: {
'X-Custom-Header': 'Scraping-Demo-Request'
}
});
console.log('Status Code:', response.statusCode);
console.log('Response Body (first 500 chars):', response.body.substring(0, 500));
// Further processing of `response.body` (e.g., JSON.parse) would happen here.
} catch (error) {
console.error('Failed to fetch data:', error instanceof Error ? error.message : error);
}
}
fetchExampleData();
Debug
Known issues
breakingThe `got-scraping` package has been officially declared End-of-Life (EOL) by its maintainers. It will no longer receive updates, bug fixes, or support. Users are strongly advised to migrate to the recommended alternative, `impit`, for new projects and consider migrating existing projects.fixFor new projects, use `impit` (npm install impit). For existing projects, evaluate the effort required to migrate to `impit` or understand that `got-scraping` will not be maintained further.
affects: >=4.0.0
breaking`got-scraping` is an ESM-only module since version 4. This means it can only be imported using `import` statements in ES modules or dynamically with `import()` in CommonJS contexts. Direct `require()` calls will result in errors.fixEnsure your project is configured as an ES module (e.g., add `"type": "module"` to `package.json`) and use `import { gotScraping } from 'got-scraping';`. If you must use CommonJS, employ dynamic imports: `const { gotScraping } = await import('got-scraping');` or `gotScraping ??= (await import('got-scraping')).gotScraping;`. affects: >=4.0.0
breakingThe package requires Node.js version 16 or newer. Running `got-scraping` on older Node.js versions may lead to instability, particularly with HTTP/2 connections, or outright failures.fixUpgrade your Node.js environment to version 16 or later using a version manager like `nvm` (e.g., `nvm install 16 && nvm use 16`).
affects: <4.0.0 (prior versions may have worked on older Node, but >=16 is explicitly required for v4)
gotchaWhen using proxies, ensure the `proxyUrl` is correctly formatted with scheme, host, port, and credentials if required (e.g., `http://username:password@myproxy.com:1234`). Incorrectly formatted URLs or invalid credentials will lead to proxy connection failures.fixDouble-check `proxyUrl` format and credentials. Ensure the proxy server is reachable and configured to accept connections from your environment. Use environment variables or a secure configuration for credentials, not hardcoded values in production.
affects: >=4.0.0
gotchaBy default, `got-scraping` generates new browser-like headers for each request. To maintain a consistent set of headers across multiple requests, you must provide a unique `sessionToken` object (any non-primitive object will work, e.g., `{}`) to reuse the same generated headers for subsequent requests within that session.fixPass a consistent `sessionToken` object: `gotScraping.get({ url: '...', sessionToken: mySessionObject });` to ensure headers are reused. A new object will always generate new headers. affects: >=4.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` in an ES module context or with an ESM-only library like `got-scraping`.
fixChange your import statement to `import { gotScraping } from 'got-scraping';` or configure your project as a CommonJS module and use dynamic `import()` for `got-scraping`. TypeError: gotScraping is not a function
`gotScraping` is an already instantiated `got` instance, not a constructor. It's meant to be called directly for requests or to chain methods like `.get()` or `.post()`.
fixDo not use `new` keyword or try to call `gotScraping()` directly. Instead, call its methods: `gotScraping.get(url)`, `gotScraping.post(options)`, or configure via `gotScraping(options)`.
Error: Proxy CONNECT Error: 407 Proxy Authentication Required
The configured proxy server requires authentication, but either no credentials were provided or they are incorrect.
fixEnsure the `proxyUrl` includes valid username and password credentials: `http://username:password@proxy.example.com:port`. Verify that the credentials are correct for your proxy.
Error: This module was compiled against Node.js version XX. You are currently running version YY. Please update Node.js to a compatible version.
`got-scraping` requires Node.js >=16, and you are running an older, incompatible version.
fixUpgrade your Node.js environment to version 16 or higher. Use a Node Version Manager (e.g., `nvm`) to easily switch versions: `nvm install 16 && nvm use 16`.
Audit
Dependencies
gotrequiredCore HTTP client library that `got-scraping` extends and builds upon.