debug

library0.3.2jsnpmunverified

The `debug` package is a lightweight and highly popular debugging utility designed for both Node.js and web browser environments. Currently stable at version `4.4.3`, it maintains a regular release cadence with frequent patch and minor updates addressing bug fixes and minor enhancements. Its core functionality revolves around providing a simple, namespace-based logging mechanism that allows developers to selectively enable or disable debug output for different parts of an application using the `DEBUG` environment variable (or `localStorage` in browsers). Key differentiators include its minimal footprint, automatic colorized output in supported terminals and browser developer tools, and the useful millisecond difference displayed between consecutive log calls, aiding in performance analysis. The project recently migrated its repository from `visionmedia/debug` to `debug-js/debug`. It is crucial to note that version `4.4.2` was compromised and users should upgrade immediately to `4.4.3` or later to avoid potential security risks.

observability http-networking

npm install debug

github ↗package ↗

INSTALL

IMPORT

SIG · DEBUG

debug

observabilityjavascriptv0.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

debug

✓ import debug from 'debug';

✗ import { debug } from 'debug';

The primary export is a default function. Named import is incorrect for the main function.

debug factory

✓ const createDebug = require('debug'); const debug = createDebug('my-namespace');

✗ const debug = require('debug'); debug('my-namespace', 'hello');

In CommonJS, `require('debug')` returns a function that must be called with a namespace to create a debugger instance.

debug.enable

✓ import debug from 'debug'; debug.enable('my-app:*');

✗ debug.enable(/my-app:.*/);

Since `4.4.0`, `.enable()` no longer supports regex input directly; use glob patterns (e.g., `*`, `-`) instead.

Demonstrates creating multiple debugger instances with different namespaces and enabling them via the `DEBUG` environment variable.

import createDebug from 'debug'; const appDebug = createDebug('my-app:main'); const workerADebug = createDebug('my-app:worker:a'); const workerBDebug = createDebug('my-app:worker:b'); // --- app.ts --- appDebug('Booting up application.'); // Simulate an HTTP server setup setTimeout(() => { appDebug('Server listening on port 3000'); // Simulate a request appDebug('GET /users'); }, 100); // --- worker.ts --- function workA() { workerADebug('Doing lots of uninteresting work...'); setTimeout(workA, Math.random() * 500); } function workB() { workerBDebug('Doing some specific work...'); setTimeout(workB, Math.random() * 1000); } workA(); workB(); // To run this example: // 1. Save as `example.ts` // 2. Transpile (e.g., `tsc example.ts`) // 3. Run with `DEBUG='my-app:*' node example.js` // On Windows PowerShell: `$env:DEBUG='my-app:*'; node example.js`

Debug

Known issues

breakingVersion `4.4.2` was compromised and contains malicious code. It is critical to avoid this version and upgrade immediately.

fix

Upgrade to `debug@4.4.3` or a later stable version. Review your `package-lock.json` or `yarn.lock` to ensure `4.4.2` is not being pulled in by transitive dependencies.

affects: 4.4.2

breakingThe `.enable()` API no longer supports regular expressions as input. Providing regex patterns will not work as expected and may lead to inefficient warnings.

fix

Migrate your `.enable()` calls from regexes to glob patterns (e.g., `*`, `-`). For instance, `debug.enable('foo:*|bar:*')` instead of `debug.enable(/(foo|bar):.*/)`. Regex functionality will not be re-added.

affects: >=4.4.0

gotchaFor optimal colorized output in Node.js, the optional `supports-color` package should be installed alongside `debug`. Without it, `debug` will only use a limited set of basic colors.

fix

Install `supports-color` as a dependency: `npm install supports-color`.

affects: >=2.x

gotchaSetting the `DEBUG` environment variable differs across Windows command prompts (CMD vs PowerShell) and Linux/macOS shells. Incorrect syntax will result in debug messages not appearing.

fix

On CMD: `set DEBUG=* & node app.js`. On PowerShell: `$env:DEBUG='*'; node app.js`. On Linux/macOS: `DEBUG='*' node app.js`.

affects: >=2.x

deprecatedOlder versions of `debug` used `String.prototype.substr()` and `RegExp.$1`, which are deprecated APIs. While `debug` has updated internally, ensure your own code avoids these where possible.

fix

Upgrade `debug` to `4.3.6` or later to benefit from internal fixes. Modernize your own codebase to use `String.prototype.substring()` or `slice()` instead of `substr()`, and named capture groups for regexes.

affects: <4.3.6

Errors

Common errors & fixes

Debug messages are not appearing in the console.

The `DEBUG` environment variable is not set or is set incorrectly for your shell.

fix

Ensure the `DEBUG` environment variable is correctly set before running your application. For example, `DEBUG='my-app:*' node app.js` (Linux/macOS), `set DEBUG=my-app:* & node app.js` (Windows CMD), or `$env:DEBUG='my-app:*'; node app.js` (Windows PowerShell).

TypeError: debug is not a function

You are trying to call the `debug` module directly without first creating a debugger instance by providing a namespace string.

fix

Always call `require('debug')` or `import debug from 'debug'` with a namespace string. Correct: `const myDebug = require('debug')('my-namespace'); myDebug('hello');`

Colors are not showing in debug output in Node.js.

The `supports-color` package is not installed, or your terminal emulator does not support colors (is not a TTY).

fix

Install `supports-color` (`npm install supports-color`) and ensure your Node.js application is running in an environment where `process.stderr` is a TTY (e.g., directly in a terminal, not piped to a file).

Upgrade

Version history

0.3.2latest on npm

Audit

Dependencies

msrequiredUsed for parsing duration strings in some internal operations.

supports-coloroptionalRecommended for full color support in Node.js environments when stderr is a TTY.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/debug-js/debug ↗

packagehttps://www.npmjs.com/package/debug ↗