pandas.read_csv

pandas.read_csv(filepath_or_buffer, *, sep=_NoDefault.no_default, delimiter=None, header='infer', names=_NoDefault.no_default, index_col=None, usecols=None, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skipinitialspace=False, skiprows=None, skipfooter=0, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=_NoDefault.no_default, skip_blank_lines=True, parse_dates=None, infer_datetime_format=_NoDefault.no_default, keep_date_col=_NoDefault.no_default, date_parser=_NoDefault.no_default, date_format=None, dayfirst=False, cache_dates=True, iterator=False, chunksize=None, compression='infer', thousands=None, decimal='.', lineterminator=None, quotechar='"', quoting=0, doublequote=True, escapechar=None, comment=None, encoding=None, encoding_errors='strict', dialect=None, on_bad_lines='error', delim_whitespace=_NoDefault.no_default, low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=_NoDefault.no_default)

将逗号分隔值 (csv) 文件读取到 DataFrame 中。

还支持可选地迭代或将文件分解为块。

有关更多帮助，请参阅 IO Tools 的在线文档。

Parameters:

filepath_or_bufferstr、path 对象或文件类对象

任何有效的字符串路径都可以接受。字符串可以是一个 URL。有效的 URL scheme 包括 http, ftp, s3, gs 和 file。对于文件 URL，需要主机名。本地文件可以是：file://localhost/path/to/table.csv。

如果要传入路径对象，pandas 接受任何 os.PathLike。

我们所说的“类文件对象”指的是具有 read() 方法的对象，例如文件句柄（例如通过内置 open 函数）或 StringIO。

sepstr, default ‘,’

用作分隔符的字符或正则表达式模式。如果 sep=None，C 引擎无法自动检测分隔符，但 Python 解析引擎可以，这意味着将使用后者，并通过 Python 内置的嗅探工具 csv.Sniffer 仅根据文件第一行有效数据自动检测分隔符。此外，长度大于 1 个字符且不同于 '\s+' 的分隔符将被解释为正则表达式，并强制使用 Python 解析引擎。请注意，正则表达式分隔符容易忽略带引号的数据。正则表达式示例：'\r\t'。

delimiterbool, default False

sep 的别名。

headerint, int 序列, ‘infer’ 或 None, 默认 ‘infer’

包含列标签并标记数据开始的行号（零索引）。默认行为是推断列名：如果未传递 names，则行为与 header=0 相同，列名从文件的第一行推断；如果列名显式传递给 names，则行为与 header=None 相同。显式传递 header=0 可以替换现有名称。标头可以是一个整数列表，用于将列指定为 MultiIndex 的行位置，例如 [0, 1, 3]。未指定的中间行将被跳过（例如，此示例中的 2 被跳过）。请注意，如果 skip_blank_lines=True，此参数将忽略注释行和空行，因此 header=0 指的是数据的第一行，而不是文件的第一行。

namesHashable 序列, 可选

要应用的列标签序列。如果文件包含标头行，则应显式传递 header=0 以覆盖列名。此列表中的重复项不允许。

index_colHashable, Hashable 序列 或 False, 可选

用作行标签的列，通过列标签或列索引表示。如果给定标签或索引的序列，将为行标签形成 MultiIndex 。

注意：index_col=False 可用于强制 pandas 不 将第一列用作索引，例如，当您遇到每行末尾有分隔符的格式错误的文件时。

usecolsHashable 或 Callable 序列, 可选

要选择的列子集，通过列标签或列索引表示。如果为类列表，则所有元素必须是位置性的（即文档列中的整数索引）或字符串，对应于用户在 names 中提供或从文档标头行推断出的列名。如果给出了 names，则不考虑文档标头行。例如，一个有效的类列表 usecols 参数可以是 [0, 1, 2] 或 ['foo', 'bar', 'baz']。元素顺序被忽略，因此 usecols=[0, 1] 与 [1, 0] 相同。要使用元素顺序保留从 data 实例化 DataFrame ，请使用 pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']] 用于 ['foo', 'bar'] 顺序的列，或 pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']] 用于 ['bar', 'foo'] 顺序。

如果为可调用对象，则该可调用函数将针对列名进行评估，返回可调用函数评估为 True 的名称。有效可调用参数的一个示例可以是 lambda x: x.upper() in ['AAA', 'BBB', 'DDD']。使用此参数可以大大加快解析时间并降低内存使用量。

dtypedtype 或 {Hashabledtype} 的字典, 可选

应用于整个数据集或单个列的数据类型。例如，{'a': np.float64, 'b': np.int32, 'c': 'Int64'} 使用 str 或 object 结合适当的 na_values 设置来保留 dtype 而不进行解释。如果指定了 converters，则它们将*代替* dtype 转换。

在 1.5.0 版本加入: 已添加对 defaultdict 的支持。指定一个 defaultdict 作为输入，其中默认值决定了未显式列出的列的 dtype。

engine{‘c’, ‘python’, ‘pyarrow’}, 可选

要使用的解析器引擎。C 和 pyarrow 引擎速度更快，而 python 引擎目前功能更完善。多线程目前仅受 pyarrow 引擎支持。

在 1.4.0 版本加入: ‘pyarrow’ 引擎被添加为一个*实验性*引擎，并且某些特性不支持，或者可能无法正确使用此引擎。

convertersdict of {HashableCallable}, optional

用于转换指定列中值的函数。键可以是列标签或列索引。

true_valueslist，optional

除了不区分大小写的“True”变体外，还将哪些值视为“True”。

false_valueslist，optional

除了不区分大小写的“False”变体外，还将哪些值视为“False”。

skipinitialspacebool，默认 False

跳过分隔符后的空格。

skiprowsint, list of int or Callable, optional

要跳过的行号（从 0 开始索引）或要跳过的行数（int）在文件开头。

如果为可调用对象，则将针对行索引调用该可调用函数，如果应跳过该行，则返回 True，否则返回 False。有效可调用参数的一个示例是 lambda x: x in [0, 2]。

skipfooterint，默认为 0

要跳过的文件底部的行数（使用 engine='c' 时不支持）。

nrowsint, optional

要读取的文件行数。用于读取大文件的一部分。

na_valuesHashable, Iterable of Hashable or dict of {HashableIterable}, optional

其他要识别为 NA/NaN 的字符串。如果传递了 dict，则为特定于列的 NA 值。默认情况下，以下值被解释为 NaN：“”、“#N/A”、“#N/A N/A”、“#NA”、“-1.#IND”、“-1.#QNAN”、“-NaN”、“-nan”、“1.#IND”、“1.#QNAN”、“<NA>”、“N/A”、“NA”、“NULL”、“NaN”、“None”、“n/a”、“nan”、“null ”。

keep_default_nabool, default True

在解析数据时是否包含默认的 NaN 值。根据是否传递了 na_values，行为如下：

• 如果 keep_default_na 为 True，并且指定了 na_values，则 na_values 将被添加到用于解析的默认 NaN 值中。

• 如果 keep_default_na 为 True，并且未指定 na_values，则仅使用默认的 NaN 值进行解析。

• 如果 keep_default_na 为 False，并且指定了 na_values，则仅使用 na_values 指定的 NaN 值进行解析。

• 如果 keep_default_na 为 False，并且未指定 na_values，则不会将任何字符串解析为 NaN。

注意，如果 na_filter 被指定为 False，则 keep_default_na 和 na_values 参数将被忽略。

na_filterbool, default True

检测缺失值标记（空字符串和 na_values 的值）。在没有任何 NA 值的数据中，将 na_filter=False 传递可以提高读取大文件的性能。

verbosebool，默认 False

指示在非数字列中放置的 NA 值的数量。

自 2.2.0 版本弃用.

skip_blank_linesbool, default True

如果为 True，跳过空白行，而不是将其解释为 NaN 值。

parse_datesbool, list of Hashable, list of lists or dict of {Hashablelist}, default False

行为如下：

• bool。如果为 True -> 尝试解析索引。注意：如果传递了 date_format 或 date_parser 参数，则自动设置为 True。

• list of int 或名称。例如，如果 [1, 2, 3] -> 尝试将列 1、2、3 分别解析为日期列。

• list of list。例如，如果 [[1, 3]] -> 将列 1 和 3 合并并解析为单个日期列。值在解析前用空格连接。

• dict，例如 {'foo' : [1, 3]} -> 将列 1、3 解析为日期，并将结果命名为 ‘foo’。值在解析前用空格连接。

如果列或索引无法表示为 datetime 数组，例如由于存在无法解析的值或时区的混合，则该列或索引将按原样返回为 object 数据类型。对于非标准的 datetime 解析，请在 to_datetime() 之后使用 read_csv() 。

注意：对于 iso8601 格式的日期，存在一个快速路径。

infer_datetime_formatbool，默认 False

如果为 True 且启用了 parse_dates，pandas 将尝试推断列中 datetime 字符串的格式，如果可以推断，则切换到更快速的方法来解析它们。在某些情况下，这可以使解析速度提高 5-10 倍。

自 2.0.0 版本弃用: 该参数的严格版本现在是默认值，传递它没有效果。

keep_date_colbool，默认 False

如果为 True 且 parse_dates 指定了合并多个列，则保留原始列。

date_parserCallable, optional

用于将字符串列序列转换为 datetime 实例数组的函数。默认使用 dateutil.parser.parser 进行转换。pandas 将尝试以三种不同的方式调用 date_parser，如果发生异常则移至下一类：1) 将一个或多个数组（根据 parse_dates 定义）作为参数传递；2) 将 parse_dates 定义的列中的字符串值按行连接成一个数组并传递；3) 为每一行调用一次 date_parser，并将一个或多个字符串（对应于 parse_dates 定义的列）作为参数传递。

自 2.0.0 版本弃用: 请改用 date_format，或先以 object 类型读入，然后根据需要应用 to_datetime() 。

date_formatstr 或 dict，格式为 {列 -> 格式}，optional

与 parse_dates 结合使用时用于解析日期的格式。strftime 用于解析时间，例如 "%d/%m/%Y" 。有关更多选择，请参阅 strftime documentation ，但请注意，"%f" 将解析到纳秒。您还可以传递：

• “ISO8601”，用于解析任何 ISO8601

  时间字符串（不一定是完全相同的格式）；

• “mixed”，分别推断每个元素的格式。这有风险，

  您可能应该与 dayfirst 一起使用它。

在 2.0.0 版本加入.

dayfirstbool，默认 False

DD/MM 格式的日期，国际和欧洲格式。

cache_datesbool, default True

如果为 True，则使用唯一的、已转换日期的缓存来应用 datetime 转换。当解析重复的日期字符串（尤其是有时区偏移的日期）时，可能会显着提高速度。

iteratorbool，默认 False

返回 TextFileReader 对象以进行迭代或使用 get_chunk() 获取块。

chunksizeint, optional

每个块要从文件中读取的行数。传递一个值将导致函数返回一个 TextFileReader 对象进行迭代。有关 iterator 和 chunksize 的更多信息，请参阅 IO Tools docs 。

compressionstr or dict, default ‘infer’

对磁盘上的数据进行即时解压缩。如果为 ‘infer’ 且 ‘filepath_or_buffer’ 是类路径，则根据以下扩展名检测压缩：’.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ 或 ‘.tar.bz2’（否则不进行压缩）。如果使用 ‘zip’ 或 ‘tar’，ZIP 文件必须只包含一个要读取的数据文件。设置为 None 表示不解压缩。也可以是一个字典，其中键 'method' 设置为 {'zip', 'gzip', 'bz2', 'zstd', 'xz', 'tar'} 中的一个，其他键值对将转发到 zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor, lzma.LZMAFile 或 tarfile.TarFile。例如，可以传递以下内容以使用自定义压缩字典进行 Zstandard 解压缩：compression={'method': 'zstd', 'dict_data': my_compression_dict}。

在 1.5.0 版本加入: 增加了对 .tar 文件的支持。

在 1.4.0 版本发生变更: Zstandard 支持。

thousandsstr（长度为 1），optional

用作数值分隔符的字符。

decimalstr（长度为 1），默认为 ‘.’

用作小数点（例如，欧洲数据使用 ‘,’）的字符。

lineterminatorstr（长度为 1），optional

用于表示换行的字符。仅在使用 C 解析器时有效。

quotecharstr（长度为 1），optional

用于表示带引号项的开始和结束的字符。带引号的项可能包含``delimiter``，这时会被忽略。

quoting{0 或 csv.QUOTE_MINIMAL, 1 或 csv.QUOTE_ALL, 2 或 csv.QUOTE_NONNUMERIC, 3 或 csv.QUOTE_NONE}，默认为 csv.QUOTE_MINIMAL

控制每个 csv.QUOTE_* 常量的字段引用行为。默认是 csv.QUOTE_MINIMAL``（即 0），这意味着只有包含特殊字符的字段才会被引用（例如，在 ``quotechar、delimiter 或 lineterminator 中定义的字符）。

doublequotebool, default True

当指定了 quotechar 且 quoting 不是 QUOTE_NONE 时，指示是否将字段内部的两个连续 quotechar 元素解释为单个 quotechar 元素。

escapecharstr（长度为 1），optional

用于转义其他字符的字符。

commentstr（长度为 1），optional

指示行中剩余部分不应被解析的字符。如果出现在行首，该行将被完全忽略。此参数必须是单个字符。像空行一样（只要 skip_blank_lines=True），完全注释掉的行将被 header 参数忽略，但不会被 skiprows 参数忽略。例如，如果 comment='#'，则用 header=0 解析 #empty\na,b,c\n1,2,3 将导致 'a,b,c' 被视为标题。

encodingstr, optional, default ‘utf-8’

读取/写入 UTF 时使用的编码（例如 'utf-8'）。List of Python standard encodings 。

encoding_errorsstr, optional, default ‘strict’

如何处理编码错误。List of possible values 。

在 1.3.0 版本加入.

dialectstr or csv.Dialect, optional

如果提供，此参数将覆盖以下参数的值（默认值或非默认值）：delimiter、doublequote、escapechar、skipinitialspace、quotechar 和 quoting。如果需要覆盖值，将发出 ParserWarning。有关更多详细信息，请参阅 csv.Dialect 文档。

on_bad_lines{‘error’, ‘warn’, ‘skip’} or Callable, default ‘error’

指定在遇到错误行（字段数过多的行）时要执行的操作。允许的值包括：

• 'error'，在遇到错误行时引发异常。

• 'warn'，在遇到错误行时引发警告并跳过该行。

• 'skip'，在遇到错误行时跳过它们，而不引发异常或警告。

在 1.3.0 版本加入.

在 1.4.0 版本加入:

• Callable，签名类似 (bad_line: list[str]) -> list[str] | None 的函数，它将处理单个错误行。bad_line 是由 sep 分割的字符串列表。如果函数返回 None，则忽略该错误行。如果函数返回的字符串列表比预期的元素多，则在删除多余元素时会发出 ParserWarning。仅当 engine='python' 时支持。

在 2.2.0 版本发生变更:

• Callable，当 engine='pyarrow' 时，签名如 pyarrow documentation 中所述的函数

delim_whitespacebool，默认 False

指定是否使用空格（例如 ' ' 或 '\t'）作为 sep 分隔符。等同于设置 sep='\s+'。如果此选项设置为 True，则不应为 delimiter 参数传递任何值。

自 2.2.0 版本弃用: 请改用 sep="\s+"。

low_memorybool, default True

将文件内部按块处理，从而降低解析时的内存使用量，但可能导致类型推断不一致。为确保没有不一致的类型，请设置为 False，或使用 dtype 参数指定类型。请注意，整个文件仍会读取到一个 DataFrame 中，请使用 chunksize 或 iterator 参数以块的形式返回数据。（仅在使用 C 解析器时有效）。

memory_mapbool，默认 False

如果为 filepath_or_buffer 提供了文件路径，则将文件对象直接映射到内存中，并直接从那里访问数据。使用此选项可以提高性能，因为不再有 I/O 开销。

float_precision{‘high’, ‘legacy’, ‘round_trip’}, optional

指定 C 引擎应使用哪个转换器来处理浮点数值。选项包括：None 或 'high' 用于普通转换器，'legacy' 用于原始的低精度 pandas 转换器，以及 'round_trip' 用于往返转换器。

storage_optionsdict, 可选

适用于特定存储连接的额外选项，例如主机、端口、用户名、密码等。对于 HTTP(S) URL，键值对将作为标头选项转发给 urllib.request.Request。对于其他 URL（例如，以 “s3://”, 和 “gcs://” 开头的 URL），键值对将转发给 fsspec.open。更多详情请参阅 fsspec 和 urllib，有关存储选项的更多示例，请参阅 here 。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}, 默认 ‘numpy_nullable’

应用于结果 DataFrame 的后端数据类型（仍处于实验阶段）。行为如下：

• "numpy_nullable"：返回支持可空 dtype 的 DataFrame （默认）。

• "pyarrow"：返回 pyarrow 支持的可空 ArrowDtype DataFrame。

在 2.0 版本加入.

Returns:

DataFrame 或 TextFileReader

逗号分隔值 (csv) 文件被返回为带有标签轴的二维数据结构。

参见

DataFrame.to_csv

将 DataFrame 写入逗号分隔值 (csv) 文件。

read_table

将通用分隔文件读取到 DataFrame 中。

read_fwf

将固定宽度格式化行的表格读入 DataFrame。

Examples

>>> pd.read_csv('data.csv')