Skip to main content
`Ctrl`+`K`

# pandas.DataFrame.loc

property DataFrame.loc

  Access a group of rows and columns by label(s) or a boolean array.

  `.loc[]` is primarily label based, but may also be used with a boolean array.

  Allowed inputs are:

  - A single label, e.g. `5` or `'a'`, (note that `5` is interpreted as a label of the index, and never as an integer position along the index).

  - A list or array of labels, e.g. `['a', 'b', 'c']`.

  - A slice object with labels, e.g. `'a':'f'`.

    Warning

    Note that contrary to usual python slices, both the start and the stop are included

  - A boolean array of the same length as the axis being sliced, e.g. `[True, False, True]`.

  - An alignable boolean Series. The index of the key will be aligned before masking.

  - An alignable Index. The Index of the returned selection will be the input.

  - A `callable` function with one argument (the calling Series or DataFrame) and that returns valid output for indexing (one of the above)

  See more at Selection by Label.

  Raises:
    KeyError

      If any items are not found.

    IndexingError

      If an indexed key is passed and its index is unalignable to the frame index.

  See also

  `DataFrame.at`

    Access a single value for a row/column label pair.

  `DataFrame.iloc`

    Access group of rows and columns by integer position(s).

  `DataFrame.xs`

    Returns a cross-section (row(s) or column(s)) from the Series/DataFrame.

  `Series.loc`

    Access group of values using labels.

  Examples

  Getting values

      >>> df = pd.DataFrame(
      ...     [[1, 2], [4, 5], [7, 8]],
      ...     index=["cobra", "viper", "sidewinder"],
      ...     columns=["max_speed", "shield"],
      ... )
      >>> df
                  max_speed  shield
      cobra               1       2
      viper               4       5
      sidewinder          7       8

  Single label. Note this returns the row as a Series.

      >>> df.loc["viper"]
      max_speed    4
      shield       5
      Name: viper, dtype: int64

  List of labels. Note using `[[]]` returns a DataFrame.

      >>> df.loc[["viper", "sidewinder"]]
                  max_speed  shield
      viper               4       5
      sidewinder          7       8

  Single label for row and column

      >>> df.loc["cobra", "shield"]
      np.int64(2)

  Slice with labels for row and single label for column. As mentioned above, note that both the start and stop of the slice are included.

      >>> df.loc["cobra":"viper", "max_speed"]
      cobra    1
      viper    4
      Name: max_speed, dtype: int64

  Boolean list with the same length as the row axis

      >>> df.loc[[False, False, True]]
                  max_speed  shield
      sidewinder          7       8

  Alignable boolean Series:

      >>> df.loc[
      ...     pd.Series([False, True, False], index=["viper", "sidewinder", "cobra"])
      ... ]
                           max_speed  shield
      sidewinder          7       8

  Index (same behavior as `df.reindex`)

      >>> df.loc[pd.Index(["cobra", "viper"], name="foo")]
             max_speed  shield
      foo
      cobra          1       2
      viper          4       5

  Conditional that returns a boolean Series

      >>> df.loc[df["shield"] > 6]
                  max_speed  shield
      sidewinder          7       8

  Conditional that returns a boolean Series with column labels specified

      >>> df.loc[df["shield"] > 6, ["max_speed"]]
                  max_speed
      sidewinder          7

  Multiple conditional using `&` that returns a boolean Series

      >>> df.loc[(df["max_speed"] > 1) & (df["shield"] < 8)]
                  max_speed  shield
      viper          4       5

  Multiple conditional using `|` that returns a boolean Series

      >>> df.loc[(df["max_speed"] > 4) | (df["shield"] < 5)]
                  max_speed  shield
      cobra               1       2
      sidewinder          7       8

  Please ensure that each condition is wrapped in parentheses `()`. See the user guide for more details and explanations of Boolean indexing.

  Note

  If you find yourself using 3 or more conditionals in `.loc[]`, consider using advanced indexing.

  See below for using `.loc[]` on MultiIndex DataFrames.

  Callable that returns a boolean Series

      >>> df.loc[lambda df: df["shield"] == 8]
                  max_speed  shield
      sidewinder          7       8

  Setting values

  Set value for all items matching the list of labels

      >>> df.loc[["viper", "sidewinder"], ["shield"]] = 50
      >>> df
                  max_speed  shield
      cobra               1       2
      viper               4      50
      sidewinder          7      50

  Set value for an entire row

      >>> df.loc["cobra"] = 10
      >>> df
                  max_speed  shield
      cobra              10      10
      viper               4      50
      sidewinder          7      50

  Set value for an entire column

      >>> df.loc[:, "max_speed"] = 30
      >>> df
                  max_speed  shield
      cobra              30      10
      viper              30      50
      sidewinder         30      50

  Set value for rows matching callable condition

      >>> df.loc[df["shield"] > 35] = 0
      >>> df
                  max_speed  shield
      cobra              30      10
      viper               0       0
      sidewinder          0       0

  Add value matching location

      >>> df.loc["viper", "shield"] += 5
      >>> df
                  max_speed  shield
      cobra              30      10
      viper               0       5
      sidewinder          0       0

  Setting using a `Series` or a `DataFrame` sets the values matching the index labels, not the index positions.

      >>> shuffled_df = df.loc[["viper", "cobra", "sidewinder"]]
      >>> df.loc[:] += shuffled_df
      >>> df
                  max_speed  shield
      cobra              60      20
      viper               0      10
      sidewinder          0       0

  Getting values on a DataFrame with an index that has integer labels

  Another example using integers for the index

      >>> df = pd.DataFrame(
      ...     [[1, 2], [4, 5], [7, 8]],
      ...     index=[7, 8, 9],
      ...     columns=["max_speed", "shield"],
      ... )
      >>> df
         max_speed  shield
      7          1       2
      8          4       5
      9          7       8

  Slice with integer labels for rows. As mentioned above, note that both the start and stop of the slice are included.

      >>> df.loc[7:9]
         max_speed  shield
      7          1       2
      8          4       5
      9          7       8

  Getting values with a MultiIndex

  A number of examples using a DataFrame with a MultiIndex

      >>> tuples = [
      ...     ("cobra", "mark i"),
      ...     ("cobra", "mark ii"),
      ...     ("sidewinder", "mark i"),
      ...     ("sidewinder", "mark ii"),
      ...     ("viper", "mark ii"),
      ...     ("viper", "mark iii"),
      ... ]
      >>> index = pd.MultiIndex.from_tuples(tuples)
      >>> values = [[12, 2], [0, 4], [10, 20], [1, 4], [7, 1], [16, 36]]
      >>> df = pd.DataFrame(values, columns=["max_speed", "shield"], index=index)
      >>> df
                           max_speed  shield
      cobra      mark i           12       2
                 mark ii           0       4
      sidewinder mark i           10      20
                 mark ii           1       4
      viper      mark ii           7       1
                 mark iii         16      36

  Single label. Note this returns a DataFrame with a single index.

      >>> df.loc["cobra"]
               max_speed  shield
      mark i          12       2
      mark ii          0       4

  Single index tuple. Note this returns a Series.

      >>> df.loc[("cobra", "mark ii")]
      max_speed    0
      shield       4
      Name: (cobra, mark ii), dtype: int64

  Single label for row and column. Similar to passing in a tuple, this returns a Series.

      >>> df.loc["cobra", "mark i"]
      max_speed    12
      shield        2
      Name: (cobra, mark i), dtype: int64

  Single tuple. Note using `[[]]` returns a DataFrame.

      >>> df.loc[[("cobra", "mark ii")]]
                     max_speed  shield
      cobra mark ii          0       4

  Single tuple for the index with a single label for the column

      >>> df.loc[("cobra", "mark i"), "shield"]
      np.int64(2)

  Slice from index tuple to single label

      >>> df.loc[("cobra", "mark i") : "viper"]
                           max_speed  shield
      cobra      mark i           12       2
                 mark ii           0       4
      sidewinder mark i           10      20
                 mark ii           1       4
      viper      mark ii           7       1
                 mark iii         16      36

  Slice from index tuple to index tuple

      >>> df.loc[("cobra", "mark i") : ("viper", "mark ii")]
                          max_speed  shield
      cobra      mark i          12       2
                 mark ii          0       4
      sidewinder mark i          10      20
                 mark ii          1       4
      viper      mark ii          7       1

  Please see the user guide for more details and explanations of advanced indexing.

  Assignment with Series

  When assigning a Series to .loc[row_indexer, col_indexer], pandas aligns the Series by index labels, not by order or position.

  Series assignment with .loc and index alignment:

      >>> df = pd.DataFrame({"A": [1, 2, 3]}, index=[0, 1, 2])
      >>> s = pd.Series([10, 20], index=[1, 0])  # Note reversed order
      >>> df.loc[:, "B"] = s  # Aligns by index, not order
      >>> df
         A   B
      0  1  20.0
      1  2  10.0
      2  3 NaN