Formatting Byte Sizes: filesize vs humanize-bytes vs pretty-bytes

When displaying storage capacity, file sizes, or network transfer rates to users, raw bytes (like 1536000) are meaningless. Developers need to convert these numbers into readable formats like "1.5 MB". While this seems simple, differences in rounding, base calculation (binary vs. decimal), and localization can lead to inconsistent user experiences. The filesize, humanize-bytes, and pretty-bytes packages solve this problem but take different approaches to flexibility and defaults.

🎛️ Configuration and Flexibility

filesize is built for power users who need exact control over every aspect of the output string. It allows you to define the number of decimal places, the base (binary or decimal), the output format (string, object, or array), and even custom spacer characters.

import { filesize } from 'filesize';

// Default usage
filesize(1024); 
// Output: "1 kB"

// Custom configuration: 2 decimal places, binary base (1024), no spacer
filesize(1024, { 
  base: 2, 
  round: 2, 
  spacer: "" 
}); 
// Output: "1.00KiB"

// Returning an object for custom rendering
filesize(1024, { output: "object" }); 
// Output: { value: 1, symbol: "kB", ... }

pretty-bytes takes an opinionated approach. It aims to provide the most readable string with minimal configuration. You can specify the number of significant digits or force a specific unit, but it generally discourages deep customization to maintain consistency.

import prettyBytes from 'pretty-bytes';

// Default usage
prettyBytes(1024);
// Output: "1 kB"

// Limiting significant digits
prettyBytes(1025, { maximumSignificantDigits: 3 });
// Output: "1.03 kB"

// Forcing a specific unit
prettyBytes(1024, { unit: 'megabyte' });
// Output: "0.001 MB"

humanize-bytes offers a simpler API with fewer configuration options. It typically accepts the number and an optional options object for precision, focusing on getting a standard string quickly without the extensive feature set of filesize.

import humanizeBytes from 'humanize-bytes';

// Default usage
humanizeBytes(1024);
// Output: "1 KB"

// With precision option
humanizeBytes(1024, { precision: 2 });
// Output: "1.00 KB"

📐 Binary (1024) vs Decimal (1000) Bases

A common source of bugs in file formatting is mixing up binary (KiB, MiB) and decimal (KB, MB) units. Operating systems often disagree on which to use.

filesize lets you explicitly toggle this behavior. By default, it often uses decimal (SI) standards, but you can switch to binary (IEC) easily.

import { filesize } from 'filesize';

const size = 1048576; // 1024 * 1024

// Decimal (SI) - Default in many configs
filesize(size, { base: 10 }); 
// Output: "1.05 MB"

// Binary (IEC)
filesize(size, { base: 2 }); 
// Output: "1 MiB"

pretty-bytes also supports this distinction but exposes it through the binary option. This is crucial when matching OS-specific reporting (e.g., macOS uses binary, while some network tools use decimal).

import prettyBytes from 'pretty-bytes';

const size = 1048576;

// Decimal (Default)
prettyBytes(size);
// Output: "1.05 MB"

// Binary
prettyBytes(size, { binary: true });
// Output: "1 MiB"

humanize-bytes generally defaults to one standard (often binary or decimal depending on the version and implementation details) and may offer less explicit control over switching bases compared to the other two. Developers must verify the default behavior in their specific version to ensure it matches their application's requirements.

import humanizeBytes from 'humanize-bytes';

// Behavior depends on library version defaults
// Often requires checking docs to confirm if 1024 or 1000 is used for 'KB'
humanizeBytes(1048576);
// Output varies: "1 MB" or "1.05 MB" depending on base logic

🌍 Localization and Symbols

How units are labeled matters for international audiences. Some libraries use "KB", others "kB", and some support full words like "Kilobytes".

filesize has robust support for custom symbols and locales. You can pass a locale string to format numbers according to regional standards (e.g., using commas vs. periods for decimals) and even override unit symbols.

import { filesize } from 'filesize';

// Using German locale for number formatting
filesize(1024.5, { locale: 'de-DE' });
// Output: "1,02 kB" (Note the comma)

// Custom symbols
filesize(1024, { symbols: { kb: "Ko" } }); // French convention example
// Output: "1 Ko"

pretty-bytes handles localization primarily through the locale option, which formats the number part of the string. It sticks to standard unit abbreviations but ensures the numeric portion respects the user's region.

import prettyBytes from 'pretty-bytes';

// French locale
prettyBytes(1024.5, { locale: 'fr-FR' });
// Output: "1,03 kB"

humanize-bytes typically provides basic number formatting but may lack the deep locale integration found in filesize. It is best suited for applications where default English formatting is acceptable or where custom post-processing is planned.

import humanizeBytes from 'humanize-bytes';

// Basic usage, locale support may be limited or absent depending on version
humanizeBytes(1024.5);
// Output: "1.02 KB"

⚠️ Maintenance and Deprecation Status

Before adding any dependency, checking its maintenance status is critical.

• filesize: Actively maintained. It is a mature library with regular updates, strong TypeScript support, and a large user base. It is safe for long-term projects.
• pretty-bytes: Actively maintained by a prominent developer in the JavaScript ecosystem. It is stable, well-tested, and widely used in modern tooling.
• humanize-bytes: Caution advised. This package has seen significantly less activity compared to the others. In some contexts, similar packages have been deprecated in favor of more robust alternatives. Always check the latest npm page and repository for deprecation notices before selecting this for a new architecture. If the repository is archived or has no recent commits, prefer filesize or pretty-bytes.

🆚 Summary of Differences

💡 Final Recommendation

For complex enterprise applications where you need to match specific design systems, support multiple locales deeply, or display data in non-standard ways (like returning objects for custom rendering), filesize is the superior choice. Its API is verbose but powerful.

For standard web applications, dashboards, and UI components where you just need a clean, readable string without spending time configuring options, pretty-bytes is the ideal default. It balances size, features, and ease of use perfectly.

Avoid humanize-bytes for new projects unless you have a specific legacy constraint, as the other two options offer better long-term stability, clearer documentation, and more active community support. Always prioritize libraries that are actively maintained to ensure security and compatibility with future JavaScript standards.