Underscore.js _.difference() Method

Beginner
5 min read
Updated: Nov 2026
4 examples
Array

Definition

Similar to _.without, but returns the values from array that are not present in the other arrays (official Underscore docs). Stable Array helper — not deprecated.

Pass the required arguments shown below. Underscore array helpers usually return a new value — check whether the source array is mutated.

Syntax

Call _.difference. Start with this line.

Underscore
_.difference(array, *others)
CallWhat it does
_.difference(array, *others)Primary signature.
_.difference(...)Call with the arguments your case needs.

Load Underscore with import _ from "underscore" (or the UMD CDN build) so these helpers are available as _.

Library declarations
Underscore
_.difference(array, *others)

Parameters

ParameterDescription
arrayRequired. Base list to take values from
*othersOptional. Zero or more arrays to subtract

Return Value

Return ValueDescription
*New array of non-matching values

Underscore.js Examples

Example 1 — Official: Subtract One Array

Keep values from the first array that are missing from the second.

Underscore
_.difference([1, 2, 3, 4, 5], [5, 2, 10]);
// → [1, 3, 4]
Try It Yourself

How It Works

  1. Base list. Start with [1, 2, 3, 4, 5].
  2. Exclude pool. Treat [5, 2, 10] as forbidden values.
  3. Filter. Drop anything that matches with ===.
  4. Result. 1, 3, and 4 remain in original order.

Example 2 — Subtract Multiple Arrays

Pass several “others” — a value is dropped if it appears in any of them.

Underscore
_.difference([1, 2, 3, 4, 5, 6], [2, 8], [5, 9]);
// → [1, 3, 4, 6]
Try It Yourself

How It Works

  1. Combine excludes. Forbidden set is roughly {2, 8, 5, 9}.
  2. Drop matches. 2 and 5 leave the base list.
  3. Ignore extras. 8 and 9 were never in the base — no effect.
  4. Keep the rest. 1, 3, 4, 6 survive in order.

Example 3 — Duplicates in the First Array Are Kept

Difference is not a set operation — repeated values stay if they are not excluded.

Underscore
_.difference([1, 1, 2, 3, 3], [2]);
// → [1, 1, 3, 3]
Try It Yourself

How It Works

  1. Only drop excluded. 2 is in the other array → removed.
  2. Keep repeats. Both 1s and both 3s remain.
  3. Not uniq. Use _.uniq afterward if you need unique values.
  4. Order. Survivors stay in first-array order.

Example 4 — Empty Arrays & No Overlap

Empty inputs and disjoint lists are safe and predictable.

Underscore
_.difference([], [1, 2]);
// → []

_.difference([1, 2, 3], []);
// → [1, 2, 3]

_.difference([1, 2], [3, 4]);
// → [1, 2]
Try It Yourself

How It Works

  1. Empty base. Nothing to keep → [].
  2. Empty others. Nothing to exclude → copy of the base.
  3. No overlap. No matches → full base returned.
  4. Safe. Never throws on empty lists.

Browser & Runtime Support

_.difference ships with Underscore.js (1.x). It runs anywhere Underscore runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install underscore.

✓ Stable · Underscore 1.x

_.difference()

Available in [email protected] (UMD / ESM). Works in evergreen browsers and current Node LTS when Underscore is loaded.

100% With Underscore 1.x
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
_.difference Underscore 1.x+

Bottom line: Safe for production once Underscore is on the page or in your bundle. Not a native browser API — load Underscore first. Prefer a pinned CDN version (e.g. [email protected]).

Frequently Asked Questions

_.difference(array, *others) returns values from the first array that are not present in any of the other arrays. Official example: _.difference([1, 2, 3, 4, 5], [5, 2, 10]) → [1, 3, 4].
As many as you like. Pass the base array first, then any number of other arrays: _.difference(a, b, c).
No. Duplicates in the first array are kept. It only drops values that appear in the other arrays: _.difference([1, 1, 2], [2]) → [1, 1].
The order of the first array. Surviving values keep their original positions.
With strict equality (===). Primitives match by value; objects and arrays match by reference.
_.without takes loose values (arr, 1, 2). _.difference takes other arrays (arr, [1, 2]). Both use strict equality on the first array.

Next: _.uniq()

Produce a duplicate-free copy of an array, optionally with a custom iteratee.

_.uniq() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

10 people found this page helpful