Skip to content
Tutorial Reference

How to Convert a NumPy Array to a Pandas DataFrame in Python

Learn how to convert NumPy arrays to Pandas DataFrames with labeled columns and indices, enabling structured data analysis and visualization in Python.

Converting NumPy arrays to Pandas DataFrames adds labeled columns and indices, transforming raw numerical data into a structured format ideal for analysis, visualization, and export.

Basic Conversion

Pass the array directly to pd.DataFrame() with column names:

import numpy as np
import pandas as pd

arr = np.array([[10, 20], [30, 40], [50, 60]])

df = pd.DataFrame(arr, columns=['A', 'B'])
print(df)

Output:

    A   B
0  10  20
1  30  40
2  50  60

Adding Custom Row Labels

Use the index parameter to assign meaningful row identifiers:

import numpy as np
import pandas as pd

arr = np.array([[10, 20], [30, 40], [50, 60]])

df = pd.DataFrame(
    arr,
    columns=['Sales', 'Profit'],
    index=['Q1', 'Q2', 'Q3']
)
print(df)

Output:

    Sales  Profit
Q1     10      20
Q2     30      40
Q3     50      60

Converting 1D Arrays

A 1D array creates a single-column DataFrame:

import numpy as np
import pandas as pd

arr_1d = np.array([100, 200, 300, 400])

df = pd.DataFrame(arr_1d, columns=['Value'])
print(df)

Output:

   Value
0    100
1    200
2    300
3    400

Multiple 1D Arrays as Columns

Combine several 1D arrays into separate columns:

import numpy as np
import pandas as pd

names = np.array(['Alice', 'Bob', 'Charlie'])
ages = np.array([25, 30, 35])
scores = np.array([85.5, 92.0, 78.5])

df = pd.DataFrame({
    'Name': names,
    'Age': ages,
    'Score': scores
})
print(df)

Output:

      Name  Age  Score
0    Alice   25   85.5
1      Bob   30   92.0
2  Charlie   35   78.5

Column Count Must Match

The number of column names must equal the number of array columns:

import numpy as np
import pandas as pd

arr = np.random.rand(5, 2)  # 5 rows, 2 columns

df = pd.DataFrame(arr, columns=['X', 'Y'])
print(df.shape)  # (5, 2)

try:
    df = pd.DataFrame(arr, columns=['X', 'Y', 'Z'])
except ValueError as e:
    print(f"Error: {e}")

Specifying Data Types

Control column types with the dtype parameter:

import numpy as np
import pandas as pd

arr = np.array([[1, 2], [3, 4], [5, 6]])

df_float = pd.DataFrame(arr, columns=['A', 'B'], dtype=float)
print(df_float.dtypes)

df = pd.DataFrame(arr, columns=['A', 'B'])
df = df.astype({'A': 'int32', 'B': 'float64'})
print(df.dtypes)

Output:

A    float64
B    float64
dtype: object
A      int32
B    float64
dtype: object

Handling Different Array Shapes

2D Arrays (Most Common)

import numpy as np
import pandas as pd

matrix = np.array([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
])

df = pd.DataFrame(matrix, columns=['Col1', 'Col2', 'Col3'])
print(df)

Output:

   Col1  Col2  Col3
0     1     2     3
1     4     5     6
2     7     8     9

3D Arrays (Requires Reshaping)

import numpy as np
import pandas as pd

tensor = np.random.randint(0, 100, size=(2, 3, 4))

flat = tensor.reshape(-1, tensor.shape[-1])  # (6, 4)
df = pd.DataFrame(flat, columns=['A', 'B', 'C', 'D'])
print(f"Shape: {df.shape}")  # (6, 4)

df_layer0 = pd.DataFrame(tensor[0], columns=['A', 'B', 'C', 'D'])
print(df_layer0)

Output:

Shape: (6, 4)
    A   B   C   D
0  51  60  86  49
1  71  37   2  36
2  38  45  88  46

Practical Examples

Random Data for Testing

import numpy as np
import pandas as pd

np.random.seed(42)

data = np.random.randn(100, 4)

df = pd.DataFrame(
    data,
    columns=['Feature1', 'Feature2', 'Feature3', 'Target']
)

print(df.head())
print(f"\nShape: {df.shape}")
print(f"\nStatistics:\n{df.describe()}")

Output:

   Feature1  Feature2  Feature3    Target
0  0.496714 -0.138264  0.647689  1.523030
1 -0.234153 -0.234137  1.579213  0.767435
2 -0.469474  0.542560 -0.463418 -0.465730
3  0.241962 -1.913280 -1.724918 -0.562288
4 -1.012831  0.314247 -0.908024 -1.412304

Shape: (100, 4)

Statistics:
         Feature1    Feature2    Feature3      Target
count  100.000000  100.000000  100.000000  100.000000
mean    -0.009811    0.033746    0.022496    0.043764
std      0.868065    0.952234    1.044014    0.982240
min     -2.025143   -1.959670   -3.241267   -1.987569
25%     -0.716089   -0.564362   -0.616727   -0.727600
50%     -0.000248   -0.024646    0.068665    0.075219
75%      0.528231    0.547116    0.701519    0.778891
max      2.314659    3.852731    2.189803    2.720169

Converting Model Predictions

import numpy as np
import pandas as pd

sample_ids = np.arange(1, 6)
predictions = np.array([0.92, 0.15, 0.78, 0.34, 0.88])
actual = np.array([1, 0, 1, 0, 1])

results = pd.DataFrame({
    'SampleID': sample_ids,
    'Prediction': predictions,
    'Actual': actual,
    'Correct': (predictions > 0.5).astype(int) == actual
})

print(results)

Output:

   SampleID  Prediction  Actual  Correct
0         1        0.92       1     True
1         2        0.15       0     True
2         3        0.78       1     True
3         4        0.34       0     True
4         5        0.88       1     True

Time Series Data

import numpy as np
import pandas as pd

dates = pd.date_range('2024-01-01', periods=5, freq='D')
values = np.array([[100, 50], [105, 52], [103, 48], [110, 55], [108, 53]])

df = pd.DataFrame(
    values,
    columns=['Price', 'Volume'],
    index=dates
)
print(df)

Output:

            Price  Volume
2024-01-01    100      50
2024-01-02    105      52
2024-01-03    103      48
2024-01-04    110      55
2024-01-05    108      53

Automatic Column Names

If you omit column names, Pandas assigns integer indices:

import numpy as np
import pandas as pd

arr = np.array([[1, 2, 3], [4, 5, 6]])

df = pd.DataFrame(arr)
print(df)

df.columns = ['A', 'B', 'C']
print(df)

Output:

   0  1  2
0  1  2  3
1  4  5  6
   A  B  C
0  1  2  3
1  4  5  6

Parameter Reference

Parameter Purpose Example
data The NumPy array np.array([[1,2],[3,4]])
columns Column header names ['X', 'Y']
index Row labels ['Row1', 'Row2']
dtype Force data type for all columns float, int32
copy Copy data (default True) False for memory efficiency

Summary

Use pd.DataFrame(array, columns=[...]) to convert NumPy arrays into labeled, structured DataFrames. Add index for custom row labels and dtype to control data types. This conversion bridges numerical computation in NumPy with the data analysis capabilities of Pandas, enabling easier visualization, grouping, and export operations.

Navigation