rguides

is.null() 

is.null(x)
Returns logical· Updated May 28, 2026· Base Functions
'null'type-checkingbase

The is.null() function tests whether an object is NULL. NULL represents the absence of a value in R.

Syntax

is.null(x)

Parameters

ParameterTypeDefaultDescription
xany object,Object to test for NULL

The function accepts any R object and returns a single logical value — there is no vectorization because NULL itself has length zero. The examples below walk through common scenarios, starting with basic NULL detection and moving through the subtle distinction between NULL and NA.

Examples

Basic usage

# NULL object
x <- NULL
is.null(x)
# [1] TRUE

# Non-NULL objects
y <- NA
is.null(y)
# [1] FALSE

z <- 1
is.null(z)
# [1] FALSE

The distinction between NULL and NA trips up many R users because both represent forms of nothing, but they behave differently in almost every context. NULL means the object itself does not exist — there is no value at all — while NA means a value exists but its content is unknown. Understanding this difference is key to debugging unexpected output in R.

NULL vs NA

# Important: NA is not NULL
is.null(NA)
# [1] FALSE

is.na(NA)
# [1] TRUE

# NULL in vectors
vec <- c(1, 2, NULL, 4)
is.null(vec)
# [1] FALSE

# NULL is removed when creating vectors
c(1, 2, NULL, 4)
# [1] 1 2 4

After understanding how NULL differs from NA, the next logical step is putting is.null() to work inside your own functions. R programmers routinely use NULL as a sentinel for optional arguments — if the caller does not provide a value, the function detects NULL and substitutes a sensible default. This pattern shows up throughout the R ecosystem, from base R’s own argument handling to package code that needs flexible interfaces.

Common patterns

Setting default values

# Function with NULL default
my_function <- function(x = NULL) {
  if (is.null(x)) {
    x <- "default"
  }
  x
}

my_function()
# [1] "default"

my_function("custom")
# [1] "custom"

Setting a default value when x is NULL is the most common pattern, but sometimes you need to initialize a variable that does not exist in the calling environment at all. The next example shows how to combine is.null() with assignment — referencing an undeclared variable directly triggers an error, but wrapping the check in is.null() lets you safely test for its existence before assigning a starting value.

Conditional initialization

# Initialize if not exists
if (is.null(my_variable)) {
  my_variable <- initialize_value()
}

Conditional initialization works well for single variables, but functions that accept configuration parameters need a more structured approach. Rather than testing each argument individually, you can use is.null() to detect whether an entire options list was provided and replace it with a sensible default. This pattern keeps function signatures clean while still allowing callers to override any setting they choose.

Checking function arguments

process <- function(data, options = NULL) {
  if (is.null(options)) {
    options <- list()  # Use empty list as default
  }
  # Process with options
}

is.null() in practice

NULL represents the absence of a value in R, it is different from NA (missing data within a vector) and from an empty vector (character(0)). A list element set to NULL is removed from the list, which is different from setting it to NA.

Use is.null() to test for NULL return values from functions that return NULL when they have nothing to return (for example, match() when no match is found, or the result of calling print() or assignment operators). It is also useful in function argument checking: if (is.null(x)) x <- default_value is a common pattern for optional arguments.

is.null() is the only safe way to test for NULL, comparing with == NULL does not work because NULL == NULL returns logical(0), not TRUE.

is.null() is often used to handle optional arguments in R functions. The idiom function(x, y = NULL) { if (is.null(y)) y <- default_y_value } allows callers to omit y entirely while the function can still use a sensible default. This pattern is idiomatic R and cleaner than missing() for most use cases. When building lists, setting an element to NULL deletes it: mylist$element <- NULL removes the element entirely.

In environments and lists, NULL has special behavior. Assigning NULL to a list element removes that element entirely from the list, whereas assigning NA keeps the element. This distinction is important when building lists dynamically, if you want to flag a missing value but keep the element present, use NA not NULL. The length(NULL) is 0, class(NULL) is "NULL", and typeof(NULL) is "NULL". Unlike NA, NULL has no concept of a missing value of a specific type, it represents the complete absence of any R object or value.

Testing for NULL with == NULL is a common mistake. x == NULL returns logical(0), not TRUE or FALSE, regardless of what x is. Always use is.null(x) for correct NULL detection.

is.null() returns TRUE only for the special NULL object, not for NA, empty vectors (integer(0)), or empty strings. A common use is checking whether a function argument was provided: if (is.null(x)) x <- default_value. Unlike is.na(), is.null() always returns a single scalar TRUE or FALSE — NULL has length zero, so there is nothing to vectorize over.

See also