Ramda.js R.difference() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Relation

Definition

Ramda’s R.difference() answers a set question: which unique items are in the first list but not in the second? You pass two lists. You get back a new array: every value from list1 that is missing from list2, with duplicates collapsed. Equality is R.equals, so objects and nested arrays match by value, not by identity. Need to drop values from a list while keeping leftover duplicates? That is R.without (List category) — same membership test, flipped argument order. Need items in either list but not both? That is R.symmetricDifference. Need a custom match instead of R.equals? That is R.differenceWith. Lodash _.difference looks similar but uses SameValueZero, so two {a: 1} objects with different identities do not match.

The official samples are the whole idea. [1,2,3,4] minus [7,6,5,4,3] is [1,2]. Swap the lists and you get [7,6,5] — difference is not commutative. Previous helper is R.countBy. Next is R.differenceWith, the same leftover with a comparator you pick.

Syntax

Call R.difference. Start with this line.

Ramda
R.difference(list1, list2)
CallWhat it does
R.difference(list1, list2)Primary signature.
R.difference(...)Call the relation helper.

Prefer import { difference } from "ramda" when you want a named import.

Library declarations
Ramda
R.difference(list1, list2)

Parameters

ParameterDescription
list1Required. Array. The list whose unique leftover items you want. Not mutated. Walked in order.
list2Required. Array. The list of values to exclude. Membership uses R.equals.

Return Value

Return ValueDescription
ArrayA new array: the set of elements in list1 not contained in list2. Duplicates from list1 appear once. Empty leftover → [].

Ramda Examples

📚 Getting Started

The official Ramda samples: numbers in both directions, then objects compared by value.

Example 1 — Official Number Samples

First list minus second. Swap the lists and the leftover set changes — difference is not commutative.

Ramda
R.difference([1, 2, 3, 4], [7, 6, 5, 4, 3]);
//=> [1, 2]

R.difference([7, 6, 5, 4, 3], [1, 2, 3, 4]);
//=> [7, 6, 5]
Try It Yourself

How It Works

That is the docs sample from ramdajs.com. In the first call, 1 and 2 are missing from the second list; 3 and 4 are not. Reverse the lists and the leftovers are 7, 6, and 5.

Example 2 — Official Object Sample

{a: 1} in the first list matches {a: 1} in the second even though they are different object identities.

Ramda
R.difference([{ a: 1 }, { b: 2 }], [{ a: 1 }, { c: 3 }]);
//=> [{ b: 2 }]
Try It Yourself

How It Works

Membership uses R.equals, not ===. Lodash _.difference would keep both objects here because SameValueZero does not deep-compare records. Previous helper is R.countBy.

📈 Practical Patterns

Cousins with flipped args or either-not-both, then the set rule, then a curried leftover for id pipelines.

Example 3 — vs R.without and R.symmetricDifference

without removes values in its first argument FROM its second. symmetricDifference keeps items that appear in only one of the two lists. differenceWith swaps R.equals for a custom predicate.

Ramda
var a = [1, 2, 3, 4];
var b = [3, 4, 5, 6];

R.difference(a, b);
//=> [1, 2]

R.without(b, a);
//=> [1, 2]

R.symmetricDifference(a, b);
//=> [1, 2, 5, 6]
Try It Yourself

How It Works

R.difference(a, b) and R.without(b, a) agree on this unique input, but the argument order is flipped. Need a custom match instead of R.equals? Use R.differenceWith. Full walkthrough of the filter cousin: R.without.

Example 4 — Result Is a Set

Duplicates in the first list collapse. without keeps leftover copies because it filters, it does not uniq.

Ramda
R.difference([1, 1, 2, 2, 3], [3]);
//=> [1, 2]

R.without([3], [1, 1, 2, 2, 3]);
//=> [1, 1, 2, 2]
Try It Yourself

How It Works

Ramda documents difference as a set: no duplicates in the result. First-seen order is kept. If you needed every leftover copy, stay with R.without.

Example 5 — Curried Leftover and Id Pipeline

Fill the first list and you get a function of the second. In a pipe, R.__ holds the incoming ids so a completed list can sit in the second slot.

Ramda
R.difference([1, 2, 3, 4])([2, 4]);
//=> [1, 3]

var assigned = [101, 102, 103, 104];
var completed = [102, 104];
R.pipe(R.difference(R.__, completed))(assigned);
//=> [101, 103]
Try It Yourself

How It Works

Because difference is arity 2, filling one argument leaves a leftover. R.difference(R.__, completed) is “this incoming list minus completed.” Lodash would write _.difference(assigned, completed) with the source array first and extra lists after it.

Browser Support

R.difference() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.

✓ Ramda 0.1.0+ · Any JS runtime

Ramda.js R.difference()

Load Ramda 0.1.0 or later via CDN or npm, then call R.difference with two lists. No extra browser API is required.

100% With Ramda 0.1.0+
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
R.difference() Universal

Bottom line: Safe in any project that includes Ramda 0.1.0 or later. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node. These labs use [email protected].

Frequently Asked Questions

R.difference(list1, list2) returns the set of all elements in the first list that are not contained in the second list. Duplicates are dropped. Type: [*] → [*] → [*]. Arity 2, curried. Added in v0.1.0.
R.difference([1,2,3,4], [7,6,5,4,3]) is [1,2]. Swap the lists and you get [7,6,5]. R.difference([{a: 1}, {b: 2}], [{a: 1}, {c: 3}]) is [{b: 2}] because objects compare with R.equals.
difference is first-minus-second and unique. without(list1, list2) removes values in list1 FROM list2 — argument order is flipped vs difference — and leftover duplicates stay. symmetricDifference keeps items in either list but not both. differenceWith uses a custom predicate instead of R.equals. Lodash _.difference is similar but uses SameValueZero, not deep equals.
No. Objects and arrays use R.equals (value equality). Two {a: 1} records match even when they are different object identities.
No. Order of the two lists matters. difference(A, B) is not the same as difference(B, A) unless the leftover sets happen to match.
No. R.difference is a stable Ramda relation helper from v0.1.0. It is not deprecated, experimental, or non-standard.

Continue to R.differenceWith()

Same first-minus-second set, with a predicate you supply for equality and leftover uniqueness.

R.differenceWith() →

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.

6 people found this page helpful