Introduction

np.asarray and np.asanyarray look nearly identical, but they make a different promise about subclasses of ndarray. asarray converts input to a plain NumPy array, while asanyarray preserves subclasses when possible. That difference matters when the caller passes objects like numpy.matrix, masked arrays, or custom ndarray subclasses.

The Core Difference

Use np.asarray when you want a normal ndarray result.

Use np.asanyarray when you want to accept array subclasses and keep their specialized behavior.

With ordinary Python lists, both functions behave the same:

1import numpy as np
2
3values = [1, 2, 3]
4print(type(np.asarray(values)))
5print(type(np.asanyarray(values)))

Both return a plain numpy.ndarray here because the input is not already a subclass.

Example With a Masked Array

Masked arrays are a simple concrete example because they are a subclass with extra behavior.

1import numpy as np
2import numpy.ma as ma
3
4masked = ma.array([1, 2, 3], mask=[False, True, False])
5
6a = np.asarray(masked)
7b = np.asanyarray(masked)
8
9print(type(a))
10print(type(b))
11print(b.mask)

What happens:

• 'np.asarray(masked) returns a plain ndarray'
• 'np.asanyarray(masked) preserves the masked-array type'

That means asarray drops the subclass-specific behavior, while asanyarray keeps it.

Why This Matters for Library Code

Suppose you are writing a helper function for numerical work. The choice of conversion function defines how much specialized array behavior you keep.

Plain-array normalization:

1import numpy as np
2
3
4def sum_as_plain_array(x):
5    arr = np.asarray(x)
6    return arr.sum()

Subclass-preserving version:

1import numpy as np
2
3
4def sum_preserving_subclass(x):
5    arr = np.asanyarray(x)
6    return arr.sum()

If your function depends only on generic array semantics and you do not want subclass surprises, asarray is the safer default. If you are building a utility that should cooperate with NumPy subclasses, asanyarray can be the better fit.

Example With a Custom Subclass

1import numpy as np
2
3
4class MyArray(np.ndarray):
5    pass
6
7
8base = np.array([1, 2, 3])
9custom = base.view(MyArray)
10
11print(type(np.asarray(custom)))
12print(type(np.asanyarray(custom)))

This prints different types:

• 'asarray gives numpy.ndarray'
• 'asanyarray keeps MyArray'

That is the core behavior in one example.

When asarray Is the Better Choice

Choose asarray when:

• you want predictable plain-array behavior
• subclass metadata or special methods could interfere with the function
• you are implementing code that is meant to work on standard arrays only

Many internal numerical helper functions use asarray for exactly this reason.

When asanyarray Is the Better Choice

Choose asanyarray when:

• you want to support NumPy subclasses naturally
• the subclass carries important semantics, such as masks or metadata
• the function should be subclass-friendly rather than normalizing everything away

This is common in library code that tries to cooperate with the broader NumPy ecosystem.

A Practical Rule of Thumb

If you are unsure, ask one question: should my function preserve subclass meaning or erase it.

If preserving subclass behavior would be surprising or dangerous, use asarray.

If stripping the subclass would lose important semantics, use asanyarray.

That is the real design decision. The syntax difference is tiny, but the API contract is not.

Common Pitfalls

• Assuming the two functions are interchangeable in library code.
• Using asarray on a masked array and silently losing the mask behavior.
• Using asanyarray when a function really requires plain ndarray semantics.
• Thinking the difference matters for ordinary lists and tuples, where it usually does not.
• Forgetting that custom subclasses may behave differently in downstream operations.

Summary

• 'np.asarray converts input to a plain ndarray.'
• 'np.asanyarray preserves ndarray subclasses when possible.'
• The difference matters mainly for masked arrays and custom subclasses.
• Use asarray for predictable normalization.
• Use asanyarray when subclass-aware behavior is part of the function contract.