{"id":17419,"library":"cli-progress","title":"Command Line Progress Bar","description":"cli-progress is a robust and highly customizable library for displaying interactive progress bars in Node.js command-line and terminal applications. Currently stable at version 3.12.0, it sees active development with several releases per year, ensuring continuous improvement and bug fixes. Key features include full control over output formatting, support for both single and multiple concurrent progress bars, and the ability to define custom tokens for displaying additional data (payloads). It offers various presets for quick styling and operates without requiring callbacks, being designed as an externally controlled UI widget suitable for both asynchronous and synchronous tasks. Unlike many alternatives, its focus on external control provides flexibility, and it includes features like FPS limiting and TTY/NOTTY mode handling.","status":"active","version":"3.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/npkgz/cli-progress","tags":["javascript","cli","tty","terminal","progress","progressbar","multibar","bar","status"],"install":[{"cmd":"npm install cli-progress","lang":"bash","label":"npm"},{"cmd":"yarn add cli-progress","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-progress","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional dependency for adding color to progress bars. Must be installed manually if colorization is desired.","package":"ansi-colors","optional":true}],"imports":[{"note":"As 'cli-progress' is a CommonJS module, ESM users should use the default import pattern (e.g., `import cliProgress from 'cli-progress';`) which leverages Node.js's CJS interop. Named imports for the main module object are not supported directly.","wrong":"import { cliProgress } from 'cli-progress';","symbol":"cliProgress","correct":"import cliProgress from 'cli-progress';"},{"note":"`SingleBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.SingleBar` after a default import. Direct named imports are incorrect for this CommonJS package.","wrong":"import { SingleBar } from 'cli-progress';","symbol":"SingleBar","correct":"const cliProgress = require('cli-progress');\nconst bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);"},{"note":"`MultiBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.MultiBar` after a default import. Direct named imports are incorrect for this CommonJS package.","wrong":"import { MultiBar } from 'cli-progress';","symbol":"MultiBar","correct":"const cliProgress = require('cli-progress');\nconst multiBar = new cliProgress.MultiBar({}, cliProgress.Presets.shades_classic);"},{"note":"`Presets` is an object property of the main `cliProgress` export. Access it via `cliProgress.Presets` in both CommonJS and ESM environments.","wrong":"const { Presets } = require('cli-progress');","symbol":"Presets","correct":"import cliProgress from 'cli-progress';\nconst theme = cliProgress.Presets.shades_classic;"}],"quickstart":{"code":"const cliProgress = require('cli-progress');\nconst colors = require('ansi-colors'); // Install 'ansi-colors' manually: npm install ansi-colors\n\n// Create new progress bar instance\nconst b1 = new cliProgress.SingleBar({\n    format: 'CLI Progress |' + colors.cyan('{bar}') + '| {percentage}% || {value}/{total} Chunks || Speed: {speed}',\n    barCompleteChar: '\\u2588',\n    barIncompleteChar: '\\u2591',\n    hideCursor: true\n});\n\n// Initialize the bar with total 200, start value 0, and a custom payload token 'speed'\nb1.start(200, 0, {\n    speed: \"N/A\"\n});\n\nlet value = 0;\nconst timer = setInterval(() => {\n    value += 5;\n    b1.update(value, { speed: `${(Math.random() * 10).toFixed(2)} MB/s` });\n\n    if (value >= b1.getTotal()) {\n        clearInterval(timer);\n        b1.stop();\n        console.log('Progress complete!');\n    }\n}, 100);\n","lang":"javascript","description":"Demonstrates a single progress bar with custom formatting, colors (using 'ansi-colors'), and a dynamic payload token update."},"warnings":[{"fix":"Upgrade to v3.3.1 or higher. If you require synchronous multi-bar updates, thoroughly test your implementation on newer versions or consider alternative approaches for synchronization.","message":"Synchronous updates on MultiBar instances could cause unexpected behavior prior to v3.3.1. The fix in v3.3.1 effectively limited synchronous updates to SingleBar instances to prevent these issues.","severity":"breaking","affected_versions":"<3.3.1"},{"fix":"Ensure `ansi-colors` is installed in your project: `npm install ansi-colors` or `yarn add ansi-colors`.","message":"Colorized progress bars (e.g., using `colors.cyan('{bar}')`) will throw a `ReferenceError` if the `ansi-colors` package is not manually installed, as it is an optional peer dependency for styling.","severity":"gotcha","affected_versions":">=1.4.1"},{"fix":"Review any code that relies on specific large ETA display values. If precise display beyond the current limit is critical, consider implementing a custom ETA formatter.","message":"The maximum displayed ETA value has been adjusted in different versions (e.g., limited to 100000s in v2.1.0, then to 1e7 seconds in v3.9.0). If the calculated ETA exceeds this limit, it will display as 'INF'.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Increase the `etaBuffer` option in the `SingleBar` or `MultiBar` constructor options to a value appropriate for your process's duration and update frequency.","message":"For very long-running processes or processes with infrequent updates, the ETA calculation may incorrectly display 'INF' if the `etaBuffer` option is not sufficiently large to capture enough historical data points.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the `ansi-colors` package: `npm install ansi-colors` or `yarn add ansi-colors`.","cause":"The `ansi-colors` package, which is used for colorizing the progress bar, has not been installed.","error":"ReferenceError: colors is not defined"},{"fix":"For ESM, use a default import for the main module object: `import cliProgress from 'cli-progress';` and then access `SingleBar` as a property: `new cliProgress.SingleBar(...)`. For CommonJS, use `const cliProgress = require('cli-progress');`.","cause":"Attempting to use ES module named imports for `SingleBar` (e.g., `import { SingleBar } from 'cli-progress';`) when 'cli-progress' is a CommonJS module.","error":"TypeError: cliProgress.SingleBar is not a constructor"},{"fix":"Ensure `start()` is called with a meaningful total, increase the `etaBuffer` option in the constructor for long-running tasks, and ensure regular updates to the progress value.","cause":"This can happen if the progress bar is initialized with zero total and current values (0/0), if the ETA calculation buffer (`etaBuffer`) is too small for long processes, or if progress updates are too infrequent.","error":"ETA displays as 'INF' or 'NULL'"}],"ecosystem":"npm","meta_description":null}