Guide · Open source

How to use debug: named logs for Node.js and browsers

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

debug is a small JavaScript utility for adding debug log lines to your code and switching them on or off by name. It works in Node.js and in web browsers, and it is modelled after Node.js core's debugging technique. After this guide you will be able to install it, create named loggers, and turn their output on from the command line or in the browser.

debugdebug-js/debug · ★ 11.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install debug in your project folder. You need Node.js and npm.
2Create a logger. Call require('debug') with a name such as your module name and store the returned function.
3Add debug lines. Pass messages to the logger, using formatters like %o for objects where useful.
4Choose what to show. Set the DEBUG environment variable to a name or wildcard, such as DEBUG=* node app.js.
5Try it in a browser. Build with browserify if needed, then set localStorage.debug and refresh the page.

Install debug with npm

debug is installed as a package. You need Node.js and npm on your machine. Run the install command in your project folder.

Prerequisites: Node.js and npm
The package is MIT licensed

npm install debug

Create a named logger

Call the debug function with the name of your module. It returns a decorated version of console.error that you pass debug statements to. Each logger can be toggled separately, and you can also toggle the module as a whole.

Use printf-style formatters such as %o to include values in the message.

Name loggers after your module, for example http or worker:a
Use a colon to separate features, such as connect:bodyParser

var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

debug('booting %o', name);

Turn logs on with the DEBUG environment variable

Output stays hidden until you enable it. The DEBUG environment variable chooses which names are shown, using space or comma-delimited names. The * character is a wildcard, and a leading - excludes names.

On Windows CMD, set the variable with the set command. In PowerShell, use $env:DEBUG instead, as shown in the README.

DEBUG=worker:* enables every logger starting with worker:
DEBUG=* enables everything that uses debug
DEBUG=*,-connect:* includes all loggers except those starting with connect:

DEBUG=* node app.js

Use debug in the browser

Build a browser-ready script with browserify. debug saves its enable state in localStorage, so you set localStorage.debug and then refresh the page.

In Chromium-based browsers such as Chrome, Brave and Electron, the console only shows debug messages if the Verbose log level is enabled.

localStorage.debug = 'worker:*'

Send output to stdout or change the output function

By default debug logs to stderr. You can change this for one namespace by setting its log method, or for all output by setting debug.log. Remember to bind console methods to console.

Per-namespace output: set log on a single logger
Global output: set debug.log, which overrides per-namespace settings

var log = debug('app:log');
log.log = console.log.bind(console);

Adjust colors, timestamps and inspection depth

Each namespace gets a color based on its name. In Node.js, colors appear when stderr is a TTY, and installing the supports-color module alongside debug is recommended. When stdout is not a TTY, debug uses Date#toISOString() for timestamps.

Environment variables beginning with DEBUG_ control options for %o and %O formatting, including DEBUG_HIDE_DATE, DEBUG_COLORS, DEBUG_DEPTH and DEBUG_SHOW_HIDDEN.

%O pretty-prints an object on multiple lines
%o pretty-prints an object on one line
%j outputs JSON
%% outputs a single percent sign

What people use it for

Finding which part of a Node.js server handles a request by logging with names like http or worker:a
Letting users of your library turn on its internal debug output by name
Debugging one module in a large app without filling the terminal with other output
Enabling browser-side logs during front-end development through localStorage

Frequently asked questions

Is debug free to use?

Yes. The project is released under the MIT licence, according to the source. Check the repository's licence file before you use it in a commercial product.

What do I need to install debug?

The source lists Node.js and npm as prerequisites. Install the package with npm install debug in your project folder.

Why are my debug messages not showing?

Output is hidden unless the DEBUG environment variable matches the logger's name. Check that the name is correct, and that you used a wildcard such as * if needed. In Chromium browsers, also make sure the Verbose log level is enabled.

How do I use debug on Windows?

In CMD, use set DEBUG=* and then run your program. In PowerShell, use $env:DEBUG set to the names you want, then run node app.js.

How is debug different from console.log?

debug lets you give each log line a name and turn groups of them on or off without editing code. Plain console.log output always appears. debug also adds colors and timing differences, as described in the README.

Are debug, winston, pino and bunyan the same?

No. debug only provides namespaced debug output, and the README does not describe log levels, file rotation or shipping logs to services. The source does not compare these projects, so check their own documentation if you need full logging.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

debug suits Node.js developers, library authors and front-end developers who want named, switchable debug output. If you need log levels, file rotation or shipping logs to a service, pick a fuller logging library such as winston, pino or bunyan. Beginners who have not used the command line may find setting environment variables awkward at first.

Install options & downloads