Written and maintained by CASRAI Editorial Board
Last updated
numpy.linspace returns a fixed number of evenly spaced values over an interval. In research code it is the usual way to build the grid of x-values for a density curve, a model prediction line or a parameter sweep, because you choose how many points you get rather than how far apart they are. Its signature in the current NumPy documentation is numpy.linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, *, device=None).
What linspace is used for in research
The NumPy documentation describes the function as returning “evenly spaced numbers over a specified interval”: num samples between start and stop. Typical research uses are a plotting grid for a fitted curve (for example the x-axis under a normal curve overlaid on a histogram or a kernel density estimate for a multimodal distribution), a sweep over a parameter such as a threshold or a smoothing bandwidth, and evaluation points for a function you want to inspect.
The reason to prefer it for these jobs is that the sample count is the thing you control. Two numbers belong in the methods note of any analysis that uses a grid: num and endpoint. Without them a reader cannot rebuild the same grid, which matters for computational reproducibility.
Install or access
NumPy is installed from the official installation page at https://numpy.org/install/. The two commands it gives are:
pip install numpyconda install numpy(inside a conda environment, created withconda create -n my-envand activated withconda activate my-env)
To keep a project isolated, the same page shows a virtual environment: python -m venv my-env, then source my-env\Scripts\activate on macOS and Linux or my-env\Scripts\activate on Windows. For sharing the environment with collaborators see sharing a reproducible conda environment. The convention is to import the package as np, and print(np.__version__) confirms which version you have.
Step-by-step: build a grid with linspace
- Import the package:
import numpy as np. - Decide the interval and the count. Pick
startandstop, then picknum. The default is 50, and it must be non-negative. - Decide whether
stopbelongs in the grid.endpoint=True(the default) includes it;endpoint=Falseleaves it out. - Call the function. The example from the NumPy documentation:
np.linspace(2.0, 3.0, num=5). - If you also need the spacing, add
retstep=True. The function then returns a pair: the samples and the step. - Record
start,stop,numandendpointin your analysis script or methods note.
Output and how to read it
The documentation examples show the three behaviours that matter most.
| Call | Result | What it shows |
|---|---|---|
np.linspace(2.0, 3.0, num=5) |
array([2. , 2.25, 2.5 , 2.75, 3. ]) |
Both ends are included; step is (stop – start) / (num – 1) = 0.25. |
np.linspace(2.0, 3.0, num=5, endpoint=False) |
array([2. , 2.2, 2.4, 2.6, 2.8]) |
The last value is dropped; step becomes (stop – start) / num = 0.2. |
np.linspace(2.0, 3.0, num=5, retstep=True) |
(array([2. , 2.25, 2.5 , 2.75, 3. ]), 0.25) |
The second element of the returned pair is the step. |
Why the step changes with endpoint
With endpoint=False the sequence is all but the last of num + 1 evenly spaced samples, so, as the documentation puts it, “the step size changes when endpoint is False”. For the same interval and the same num, a grid with the endpoint and a grid without it have different spacing (0.25 against 0.2 in the example above). This is the quickest check when a plotted curve looks slightly shifted: confirm which setting the code uses. Use retstep=True to read the actual spacing instead of computing it by hand.
Arrays as start and stop
When start and stop are array-like, axis (default 0) decides where the samples go in the result; axis=-1 puts them on the last axis. Running np.linspace([0, 10], [1, 20], 3) returns a 3 by 2 array with one column per interval, and the same call with axis=-1 returns a 2 by 3 array with one row per interval.
Integer output
The dtype is inferred from start and stop, but “the inferred dtype will never be an integer; float is chosen even if the arguments would produce an array of integers”. If you pass an integer dtype yourself, then since NumPy 1.20.0 values are rounded towards negative infinity rather than towards zero. The old behaviour is reproduced by np.linspace(start, stop, num).astype(np.int_). Truncating a grid to integers repeats some values, so check the result before using it as an index.
linspace or arange: counting versus stepping
numpy.arange takes a step; linspace takes a count. For floating-point steps the arange documentation warns that the length is the ceiling of (stop – start) / step, that “the last element may be greater than stop”, and that “the length of the output might not be numerically stable”. It also states that the actual step is dtype(start + step) - dtype(start) and not step. For a non-integer step such as 0.1, the arange documentation recommends linspace, whose length is fixed by num. Its own example is np.linspace(0, 5, 10, endpoint=False), which gives array([0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5, 4. , 4.5]).
In practice: if the number of points matters (a plotting grid with a known resolution, a fixed number of parameter values), use linspace. If the spacing matters and the values are integers, arange is the direct tool.
Troubleshooting
“Importing the numpy c-extensions failed”
This is an installation or environment problem, not a linspace problem. The NumPy installation page points to the project’s ImportError troubleshooting guide at https://numpy.org/doc/stable/user/troubleshooting-importerror.html.
The grid has one point too few or too many
Check num and endpoint. num counts the samples returned, so an interval of 10 divided into 10 steps needs num=11 when the endpoint is included.
The values came back as floats, not integers
This is by design (see Integer output above). Pass dtype explicitly if you need integers, and expect rounding towards negative infinity.
linspace and arange disagree
They define the sequence differently: one by count, the other by step and a ceiling on the length. Use the lengths from each call to see which one is producing the extra element.
Keyword-only device argument
NumPy 2.0.0 added the keyword-only device parameter for Array API compatibility; if you pass it, the value must be "cpu". Most code never needs it.
Free alternatives
These are the related NumPy functions listed in the linspace documentation’s “See also” section, plus the one that takes a step instead of a count.
| Function | You specify | Spacing |
|---|---|---|
numpy.linspace |
start, stop, count | Evenly spaced |
numpy.arange |
start, stop, step | Evenly spaced; length can be unstable for float steps |
numpy.geomspace |
start, stop, count | Evenly spaced on a log scale (a geometric progression) |
numpy.logspace |
start and stop as exponents, count | Evenly spaced on a log scale; endpoints are given as logarithms |
FAQ
What is the default number of samples in numpy linspace?
50. The num parameter defaults to 50 and must be non-negative.
Does linspace include the stop value?
Yes by default, because endpoint=True. Set endpoint=False to exclude it; the step then changes, as shown above.
What is the difference between linspace and arange?
linspace fixes the number of points; arange fixes the step. With float steps, arange can return a last element beyond stop and an unstable length, which is why its documentation recommends linspace for non-integer steps.
Can linspace return integers?
Not by inference. Pass an integer dtype to get integers; values are rounded towards negative infinity since NumPy 1.20.0.
How do I get the spacing between points?
Call it with retstep=True; the second element of the returned pair is the step.
Sources
- NumPy documentation,
numpy.linspace: https://numpy.org/doc/stable/reference/generated/numpy.linspace.html (checked 2026-10-29). - NumPy documentation,
numpy.arange: https://numpy.org/doc/stable/reference/generated/numpy.arange.html (checked 2026-10-29). - NumPy installation instructions: https://numpy.org/install/ (checked 2026-10-29).
