{"id":17394,"library":"urllib","title":"urllib for Node.js","description":"urllib is a comprehensive HTTP client library for Node.js, designed to simplify URL interactions in complex scenarios. It provides features like basic and digest authentication, automatic redirection handling, configurable timeouts, and support for various request and response data types. The current stable version is 4.9.0, with a parallel maintenance branch for version 3 (latest 3.27.3). The library is built on top of Node.js's `undici` API, offering modern performance and adherence to web standards. It has a regular release cadence, with frequent bug fixes and minor feature additions across both major versions. Key differentiators include its robust handling of HTTP complexities often found in enterprise environments and its strong TypeScript support.","status":"active","version":"4.9.0","language":"javascript","source_language":"en","source_url":"git://github.com/node-modules/urllib","tags":["javascript","urllib","http","urlopen","curl","wget","request","https","undici","typescript"],"install":[{"cmd":"npm install urllib","lang":"bash","label":"npm"},{"cmd":"yarn add urllib","lang":"bash","label":"yarn"},{"cmd":"pnpm add urllib","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern Node.js ESM modules, use named imports. While `require` might work via an interop layer in some ESM setups, directly using `import` is the idiomatic and most reliable approach.","wrong":"const { request } = require('urllib'); // Incorrect in a pure ESM module context","symbol":"request","correct":"import { request } from 'urllib';"},{"note":"For Node.js CommonJS modules, use the `require` syntax. Attempting to use `import` in a `.js` file without `\"type\": \"module\"` in `package.json` will result in a `SyntaxError`.","wrong":"import { request } from 'urllib'; // Incorrect in a CommonJS module context","symbol":"request (CommonJS)","correct":"const { request } = require('urllib');"},{"note":"To create a custom `urllib` instance with specific global configurations or a custom `undici` dispatcher, use the named `create` factory function. Direct class instantiation or default imports are generally not recommended in current versions.","wrong":"import urllib from 'urllib'; // Default import is not the primary API\nconst client = new urllib(); // Class instantiation is not the recommended pattern","symbol":"create (for custom instance)","correct":"import { create } from 'urllib';\nconst client = create({ /* options */ });"}],"quickstart":{"code":"import { request } from 'urllib';\n\nasync function fetchData() {\n  try {\n    const { data, res } = await request('https://cnodejs.org/api/v1/topics?limit=5', {\n      dataType: 'json', // Automatically parse response as JSON\n      method: 'GET',\n      timeout: 5000,   // 5 seconds timeout\n      headers: {\n        'User-Agent': 'urllib-checklist-example/1.0'\n      }\n    });\n    console.log('Status: %s', res.status);\n    console.log('Headers: %j', res.headers);\n    console.log('First topic title: %s', data.data[0].title);\n  } catch (error) {\n    console.error('Request failed:', error.message);\n  }\n}\n\nfetchData();\n","lang":"typescript","description":"Demonstrates a basic GET request to a public API, parsing the response as JSON, and handling potential errors. It includes common options like `dataType`, `method`, `timeout`, and `headers`."},"warnings":[{"fix":"Review the official changelog for specific breaking changes between v3 and v4. Ensure your Node.js environment meets the `>=18.19.0` requirement. Test thoroughly after upgrading.","message":"urllib v4 introduces significant internal changes by basing its API on `undici`, which may lead to subtle behavioral differences or require Node.js 18.19.0+. While the `request` API remains largely consistent, deep integrations or reliance on internal `urllib` behaviors might require adjustments.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If your application relies on automatic decompression (e.g., `gzip`, `deflate`), explicitly set `compressed: true` in your request options. Otherwise, you might receive raw compressed data.","message":"The `compressed` option, which controls automatic decompression of response bodies, changed its default value to `false`. Previously, it might have defaulted to `true` or been implicitly handled, leading to uncompressed responses if not explicitly set.","severity":"breaking","affected_versions":">=4.6.11"},{"fix":"Always provide the `timeout` option as a number representing milliseconds (e.g., `timeout: 5000` for 5 seconds) to ensure consistent behavior across all `urllib` versions and avoid potential parsing issues.","message":"The `timeout` option in `urllib` historically had variations in how it accepted string formats (e.g., '2s'). While v4.7.1 added compatibility for `urllib@2` string formats, relying on number-based timeouts (milliseconds) is the most robust and consistent approach across versions.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Prefer `import { request } from 'urllib';` for making requests directly. If you need a custom `urllib` instance with specific configurations (e.g., a custom dispatcher), use `import { create } from 'urllib';`.","message":"The direct `urllib` class constructor or `new urllib()` pattern is generally deprecated in favor of named exports like `request` for simple calls or `create` for custom instances. Relying on default exports or class instantiation can lead to unexpected behavior or future breakage.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Regularly run `npm audit` or `snyk test` in your project and update `urllib` to the latest recommended version, especially for patch releases, to ensure you have the most secure version.","message":"Security vulnerabilities in `urllib` or its dependencies are tracked by Snyk. While the library actively addresses them, it's crucial to regularly update to the latest patch versions to mitigate known risks.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For Node.js CommonJS files, change `import { request } from 'urllib';` to `const { request } = require('urllib');`. If you intend to use ESM, ensure your `package.json` has `\"type\": \"module\"` or files end with `.mjs`.","cause":"Attempting to use ES module `import` syntax in a Node.js CommonJS module, or running in an older Node.js version not configured for ESM.","error":"SyntaxError: Named export 'request' not found. The requested module 'urllib' does not provide an export named 'request'"},{"fix":"Ensure you `await` the `request` call: `const { data, res } = await request(...);`. Remember that `await` can only be used inside `async` functions.","cause":"Missing `await` keyword when calling `urllib.request`, causing the result to be a Promise instead of the resolved value.","error":"TypeError: Cannot destructure property 'data' of 'undefined' or 'null' as it is null."},{"fix":"Increase the `timeout` option in `request` (e.g., `timeout: 10000` milliseconds). Verify network connectivity and firewall rules. The target server might be down or heavily loaded.","cause":"The network connection timed out before a response could be established or fully received.","error":"Error: connect ETIMEDOUT <IP>:<PORT>"},{"fix":"Inspect the raw response content (e.g., by logging `data.toString()`) to understand why it's not valid JSON. You might need to remove `dataType: 'json'` and manually parse the `data` buffer/string after checking `res.headers['content-type']` or handle non-JSON responses gracefully.","cause":"The `dataType: 'json'` option was used, but the server responded with non-JSON content or malformed JSON. The error message indicates an attempt to parse a string that starts like JSON but is invalid or unexpected.","error":"SyntaxError: Unexpected token '\"', \"{ \"error\": \"In\"...\" is not valid JSON"}],"ecosystem":"npm","meta_description":null}