Skip to main content
`Ctrl`+`K`

# pandas.Series.str.split

Series.str.split(pat=None, *, n=-1, expand=False, regex=None)

  Split strings around given separator/delimiter.

  Splits the string in the Series/Index from the beginning, at the specified delimiter string.

  Parameters:
    pat str or compiled regex, optional

      String or regular expression to split on. If not specified, split on whitespace.

    n int, default -1 (all)

      Limit number of splits in output. `None`, 0 and -1 will be interpreted as return all splits.

    expand bool, default False

      Expand the split strings into separate columns.

      - If `True`, return DataFrame/MultiIndex expanding dimensionality.

      - If `False`, return Series/Index, containing lists of strings.

    regex bool, default None

      Determines if the passed-in pattern is a regular expression:

      - If `True`, assumes the passed-in pattern is a regular expression

      - If `False`, treats the pattern as a literal string.

      - If `None` and pat length is 1, treats pat as a literal string.

      - If `None` and pat length is not 1, treats pat as a regular expression.

      - Cannot be set to False if pat is a compiled regex

  Returns:
    Series, Index, DataFrame or MultiIndex

      Type matches caller unless `expand=True` (see Notes).

  Raises:
    ValueError

      - if regex is False and pat is a compiled regex

  See also

  `Series.str.rsplit`

    Splits string around given separator/delimiter, starting from the right.

  `Series.str.join`

    Join lists contained as elements in the Series/Index with passed delimiter.

  `re.split`

    Standard library version for split with `regex=True`.

  `str.split`

    Standard library version for split with `regex=False`.

  `str.rsplit`

    Standard library version for rsplit.

  Notes

  The handling of the n keyword depends on the number of found splits:

  - If found splits > n, make first n splits only

  - If found splits <= n, make all splits

  - If for a certain row the number of found splits is less than the maximum number of splits found across all rows, append None for padding if `expand=True`

  If using `expand=True`, Series and Index callers return DataFrame and MultiIndex objects, respectively. The number of columns equals the maximum number of splits found in the data plus one and can be less than `n + 1`; n is an upper bound on the number of splits, not a guaranteed output width. To get a fixed number of columns, reindex the result, e.g. `.reindex(range(n + 1), axis=1)`.

  Use of regex =False with a pat as a compiled regex will raise an error.

  Examples

      >>> s = pd.Series(
      ...     [
      ...         "this is a regular sentence",
      ...         "https://docs.python.org/3/tutorial/index.html",
      ...         np.nan,
      ...     ]
      ... )
      >>> s
      0                       this is a regular sentence
      1    https://docs.python.org/3/tutorial/index.html
      2                                              NaN
      dtype: str

  In the default setting, the string is split by whitespace.

      >>> s.str.split()
      0                   [this, is, a, regular, sentence]
      1    [https://docs.python.org/3/tutorial/index.html]
      2                                                NaN
      dtype: object

  Without the n parameter, the outputs of rsplit and split are identical.

      >>> s.str.rsplit()
      0                   [this, is, a, regular, sentence]
      1    [https://docs.python.org/3/tutorial/index.html]
      2                                                NaN
      dtype: object

  The n parameter can be used to limit the number of splits on the delimiter. The outputs of split and rsplit are different.

      >>> s.str.split(n=2)
      0                     [this, is, a regular sentence]
      1    [https://docs.python.org/3/tutorial/index.html]
      2                                                NaN
      dtype: object

      >>> s.str.rsplit(n=2)
      0                     [this is a, regular, sentence]
      1    [https://docs.python.org/3/tutorial/index.html]
      2                                                NaN
      dtype: object

  The pat parameter can be used to split by other characters.

      >>> s.str.split(pat="/")
      0                         [this is a regular sentence]
      1    [https:, , docs.python.org, 3, tutorial, index...
      2                                                  NaN
      dtype: object

  When using `expand=True`, the split elements will expand out into separate columns. If NaN is present, it is propagated throughout the columns during the split.

      >>> s.str.split(expand=True)
                                                     0    1    2        3         4
      0                                           this   is    a  regular  sentence
      1  https://docs.python.org/3/tutorial/index.html  NaN  NaN      NaN       NaN
      2                                            NaN  NaN  NaN      NaN       NaN

  For slightly more complex use cases like splitting the html document name from a url, a combination of parameter settings can be used.

      >>> s.str.rsplit("/", n=1, expand=True)
                                          0           1
      0          this is a regular sentence         NaN
      1  https://docs.python.org/3/tutorial  index.html
      2                                 NaN         NaN

  Remember to escape special characters when explicitly using regular expressions.

      >>> s = pd.Series(["foo and bar plus baz"])
      >>> s.str.split(r"and|plus", expand=True)
          0   1   2
      0 foo bar baz

  Regular expressions can be used to handle urls or file names. When pat is a string and `regex=None` (the default), the given pat is compiled as a regex only if `len(pat) != 1`.

      >>> s = pd.Series(["foojpgbar.jpg"])
      >>> s.str.split(r".", expand=True)
                 0    1
      0  foojpgbar  jpg

      >>> s.str.split(r"\.jpg", expand=True)
                 0 1
      0  foojpgbar

  When `regex=True`, pat is interpreted as a regex

      >>> s.str.split(r"\.jpg", regex=True, expand=True)
                 0 1
      0  foojpgbar

  A compiled regex can be passed as pat

      >>> import re
      >>> s.str.split(re.compile(r"\.jpg"), expand=True)
                 0 1
      0  foojpgbar

  When `regex=False`, pat is interpreted as the string itself

      >>> s.str.split(r"\.jpg", regex=False, expand=True)
                     0
      0  foojpgbar.jpg