BUG: Series.str.zfill() behaves differently than str.zfill() from standard library

doc/source/whatsnew/v1.5.0.rst

@@ -530,6 +530,7 @@ Conversion
 Strings
 ^^^^^^^
 - Bug in :meth:`str.startswith` and :meth:`str.endswith` when using other series as parameter _pat_. Now raises ``TypeError`` (:issue:`3485`)
+- Bug in :meth:`Series.str.zfill` does not behave the same as ``str.zfill()`` from standard library (:issue:`20868`)
 -
 
 Interval

pandas/core/strings/accessor.py

@@ -1683,19 +1683,23 @@ def zfill(self, width):
 
         Note that ``10`` and ``NaN`` are not strings, therefore they are
         converted to ``NaN``. The minus sign in ``'-1'`` is treated as a
-        regular character and the zero is added to the left of it
+        special character and the zero is added to the right of it
         (:meth:`str.zfill` would have moved it to the left). ``1000``
         remains unchanged as it is longer than `width`.
 
         >>> s.str.zfill(3)
-        0     0-1
+        0     -01
         1     001
         2    1000
         3     NaN
         4     NaN
         dtype: object
         """
-        result = self.pad(width, side="left", fillchar="0")
+        if not is_integer(width):
+            msg = f"width must be of integer type, not {type(width).__name__}"
+            raise TypeError(msg)
+        f = lambda x: x.zfill(width)
+        result = self._data.array._str_map(f)
         return self._wrap_result(result)
 
     def slice(self, start=None, stop=None, step=None):

pandas/tests/strings/test_strings.py

@@ -799,3 +799,19 @@ def test_str_accessor_in_apply_func():
     expected = Series(["A/D", "B/E", "C/F"])
     result = df.apply(lambda f: "/".join(f.str.upper()), axis=1)
     tm.assert_series_equal(result, expected)
+
+
+def test_zfill():
+    # https://github.com/pandas-dev/pandas/issues/20868
+    value = Series(["-2", "+5"])
+    wid = "a"
+    msg = f"width must be of integer type, not {type(wid).__name__}"
+    with pytest.raises(TypeError, match=msg):
+        value.str.zfill(wid)
+    value = Series(["-1", "1", "1000", 10, np.nan])
+    expected = Series(["-01", "001", "1000", np.nan, np.nan])
+    tm.assert_series_equal(value.str.zfill(3), expected)
+
+    value = Series(["-2", "+5"])
+    expected = Series(["-0002", "+0005"])
+    tm.assert_series_equal(value.str.zfill(5), expected)