[BUG] `mx.expand_dims` docs: the Args section names `axes`, but the parameter is `axis`

Open Beginner friendly
  • Is something wrong?
#4,829 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

@Redempt1onzzZZ is already working on this.

Since Nov 4, 2026.

  • #4830 by @Redempt1onzzZZ — open

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
cpp, machine-learning, python
Domain
documentation, machine-learning

Research direction

The issue points to the mx.expand_dims docstring in python/src/ops.cpp:260 and its binding at line 249. Read those entries and check how nearby operation docstrings name arguments. Update the Args entry to match the axis parameter, then confirm the generated docstring uses that name.

Written by the indexing model from the issue text.

Description

☑️ I understand it is strictly prohibited to use AI to write issues.

Describe the bug
In the docstring of mx.expand_dims, the signature line uses axis, but the Args section documents axes (int or tuple(int)): The index of the inserted dimensions. Passing axes= raises TypeError.

To Reproduce

Include code snippet

import mlx.core as mx

doc = mx.expand_dims.__doc__
print(doc.splitlines()[0])                       # signature line uses `axis`
print([l.strip()[:45] for l in doc.splitlines() if l.strip().startswith(("a (", "axes", "axis"))])

a = mx.zeros((2,))
print(mx.expand_dims(a, axis=0).shape)
mx.expand_dims(a, axes=0)                        # name taken from the Args section

Output:

expand_dims(a: array, /, axis: int | Sequence[int], *, stream: StreamOrDevice = None) -> array
['a (array): Input array.', 'axes (int or tuple(int)): The index of the in']
(1, 2)
TypeError: expand_dims(): incompatible function arguments. The following argument types are supported:
    1. expand_dims(a: array, /, axis: int | Sequence[int], *, stream: StreamOrDevice = None) -> array

Invoked with types: mlx.core.array, kwargs = { axes: int }

Expected behavior
The Args entry is named axis, matching the signature and the binding.

Desktop (please complete the following information):

  • OS Version: macOS 26.6.2 (arm64)
  • Version: mlx 0.32.4

Additional context
Args entry: python/src/ops.cpp:260; binding argument "axis"_a: python/src/ops.cpp:249.

Dominant language
C++
Stars
29.1k
Forks
2.4k
Avg merge
3d 20h
Merged PRs (30d)
103

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ml-explore/mlx

All issues in ml-explore/mlx

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.