Skip to content
Get packs

debug

A tiny debugging helper for JavaScript that prints namespaced log messages, toggled by the DEBUG variable.

GitHub Download 4.4.3
Stars
11.5k
Forks
997
Licence
MIT
Language
JavaScript
Last update
22 days ago
Type
Library

What it is

debug is a small JavaScript utility that lets you add debug log lines to code and switch them on or off by name. You give each logger a name, such as the name of your module, and then choose which names to show using the DEBUG environment variable. It works in Node.js and in web browsers, and it is modelled after Node.js core's debugging approach.

  • Print timing and request details from a Node.js HTTP server only when DEBUG=http is set
  • Turn on debug output for one worker module (for example DEBUG=worker:a) while leaving others silent
  • Enable browser debug logs by setting localStorage.debug and refreshing the page
  • Add custom formatters, such as printing a Buffer as hex with %h

Great for

  • Node.js developers who want named, toggleable log output instead of plain console.log calls
  • Library authors who want their users to turn on internal debug output selectively
  • Developers debugging a specific part of a larger app without flooding the terminal
  • Front-end developers who want to enable browser-side logs through localStorage

Not ideal for

  • People who need a full logging system with log levels, file rotation, or shipping logs to services, since the README describes only namespaced debug output
  • Beginners who have never used the command line, since enabling output relies on setting environment variables
Step-by-step guide: how to use debugInstall, first run, examples, tips and FAQs
debug alternativesdebug vs PySnooperdebug vs winstondebug vs pinodebug vs IceCream

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js · npm

    Install the package with npm

    npm install debug
  2. 2

    Run it

    • Install the package with npm install debug
    • In your code, add const debug = require('debug')('myapp') and call debug('message')
    • Run your program with DEBUG=myapp set in the environment, for example DEBUG=myapp node app.js
    • On Windows PowerShell, set the variable with $env:DEBUG='myapp' before running node app.js
  3. 3

    Get the most out of it

    • Install supports-color alongside debug to get more colors in Node.js output
    • Use namespaces like yourlib:feature so users can filter output with wildcards
    • Use the %o and %O formatters to inspect objects, and DEBUG_DEPTH or DEBUG_SHOW_HIDDEN to control them
    • Add custom formatters through debug.formatters for types you often log
    • Set DEBUG_HIDE_DATE or rely on the ISO timestamp output when logging to non-TTY files

Downloads

Source code (.zip)master branch · straight from GitHubRelease 4.4.3Release notes and source

Strengths

  • Very small and simple API: call the exported function with a name and use the returned logger
  • Output can be filtered with wildcards and exclusions, such as DEBUG=*,-connect:*
  • Works in both Node.js and browsers, with colors and millisecond timing shown in the output

Trade-offs

  • Colors in Node.js are better when the optional supports-color module is installed alongside it, and browser console output may need the Verbose level enabled
  • Setting DEBUG differs between Windows CMD and PowerShell, which adds friction on Windows
  • Output goes to stderr by default, so it may need configuring if you expect stdout

How it compares

ProjectStarsTypeLevelUpdatedBest for
debug (this)11.5kLibrarybeginner22 days agoNode.js developers who want named, toggleable log output instead of plain console.log calls
winston24.5kLibraryintermediate4 months agoNode.js developers who need structured or file-based application logs
pino18.3kLibrarybeginner30 days agoNode.js backend developers who want structured JSON logs
mocha22.9kLibraryintermediate5 days agoJavaScript and Node.js developers who want automated tests for their code
PySnooper16.6kLibrarybeginner5 months agoDevelopers who want quick insight into a function without setting up a full debugger
turndown11.5kLibrarybeginner19 days agoDevelopers who need to convert HTML content, such as web pages or rich text editor output, into Markdown

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.