Skip to main content

Python Pandas: How to Set Column Names When Reading CSV File (read_csv)

When reading data from a Comma-Separated Values (CSV) file into a Pandas DataFrame using pd.read_csv(), you often need to define or override the column names. The CSV file might not have a header row, or you might want to use more descriptive or standardized names than those provided in the file.

This guide explains how to use the names and header parameters of pd.read_csv() to effectively set column names for your DataFrame upon creation.

The Need for Custom Column Names When Reading CSVs​

  • No Header in File: The CSV data might start directly with data rows, lacking a header row to define column names. Pandas would default to assigning integer column names (0, 1, 2,...).
  • Replacing Existing Headers: The CSV might have a header row, but you want to use different, more meaningful, or standardized column names in your DataFrame.
  • Consistency: Ensuring consistent column naming across different data sources.

Example CSV File (employees_no_header.csv): This file has no header row.

Alice,Smith,50000,HR
Bob,Johnson,75000,Engineering
Charlie,Brown,60000,HR

Example CSV File (employees_with_header.csv): This file has a header row.

first,last,annual_salary,dept
Alice,Smith,50000,HR
Bob,Johnson,75000,Engineering
Charlie,Brown,60000,HR

Scenario 1: CSV File WITHOUT a Header Row​

If your CSV file lacks a header row, you must provide column names; otherwise, Pandas will use default integer column names (0, 1, 2, ...).

Using the names Parameter​

The names parameter of pd.read_csv() accepts a list of strings to be used as column names. When names is provided and header is not explicitly set to an integer row number, pd.read_csv() assumes there's no header in the file.

import pandas as pd

# Assume 'employees_no_header.csv' is in the same directory
csv_file_no_header = 'employees_no_header.csv'

# Define the desired column names
custom_column_names = ['FirstName', 'LastName', 'Salary', 'Department']

# ✅ Read CSV without header, providing custom names
df_no_header = pd.read_csv(
    csv_file_no_header,
    names=custom_column_names
    # header=None is implied when 'names' is provided and header is not an integer
)

print("DataFrame from CSV without header, using custom names:")
print(df_no_header)
  • names=custom_column_names: Assigns your list of names to the columns.
  • header=None: If names is specified, header defaults to None, meaning Pandas treats the first line of the CSV as data. You can explicitly set header=None for clarity, but it's often not needed if names is provided.

Scenario 2: CSV File WITH a Header Row (Replacing Existing Headers)​

If your CSV file does have a header row, but you want to replace those names with your own, you need to use both the names parameter and tell Pandas which row in the CSV contains the (old) header using the header parameter.

Using names and header=0​

Set header=0 to indicate that the first row (index 0) of the CSV file contains the headers you want to discard and replace with those provided in names.

import pandas as pd

# Assume 'employees_with_header.csv' is in the same directory
csv_file_with_header = 'employees_with_header.csv'

# Define the new desired column names
new_custom_names = ['GivenName', 'FamilyName', 'AnnualIncome', 'Division']

# ✅ Read CSV with header, providing new names and specifying old header row
df_replace_header = pd.read_csv(
    csv_file_with_header,
    names=new_custom_names,
    header=0 # Tells Pandas row 0 is the header to be replaced
)

print("DataFrame from CSV with header, replacing original headers:")
print(df_replace_header)
  • header=0: Pandas reads the first row as the header but then discards these names because names is also provided. The data reading starts from the line after this specified header row.
  • If you omit header=0 (or set header=None) when names is provided and the CSV does have a header, that header row will be incorrectly read as a data row.

Understanding the header Parameter​

  • header=None: No header row in the CSV. If names is also not provided, columns will be 0, 1, 2, ...
  • header=0 (default if names is not provided): The first row of the CSV is used for column names.
  • header=N: The Nth row (0-indexed) of the CSV is used for column names. Rows above N are skipped.
  • When names is provided:
    • If header is not set or is None: Assumes no header in CSV, names are used, first line is data.
    • If header=0 (or other integer N): Row 0 (or N) is considered the header line in the file but is replaced by the names you provide. Data reading starts from the line after the specified header row.

Reading a Subset of Rows (nrows) with Custom Names​

When working with very large CSV files, you might only want to read the first few rows (nrows) while still applying custom column names. This is useful for quick inspection or if you only need a sample.

import pandas as pd

csv_file_no_header = 'employees_no_header.csv' # Assume this file has many rows
custom_column_names = ['FirstName', 'LastName', 'Salary', 'Department']

# ✅ Read only the first 2 data rows, applying custom names
df_subset_rows = pd.read_csv(
    csv_file_no_header,
    names=custom_column_names,
    nrows=2
)

print("Reading first 2 rows with custom names:")
print(df_subset_rows)
  • nrows=2: Reads only the first two data rows from the file after considering the header and names logic.

Conclusion​

Setting column names when reading a CSV file with Pandas pd.read_csv() is controlled by the names and header parameters:

  • For CSVs WITHOUT a header row: Use pd.read_csv(filepath, names=['col1', 'col2', ...]).
  • For CSVs WITH a header row that you want to REPLACE: Use pd.read_csv(filepath, names=['new_col1', ...], header=0). This tells Pandas to use the first row in the file as the (old) header position but to use your provided names instead.

Understanding these parameters allows you to correctly structure your DataFrame with meaningful column names right from the data loading step, regardless of the CSV file's header status.

Table of Contents