refactor: deprecate pytz in favor of builtin zoneinfo

JoLo90 · JoLo90 · commit 82875c7f81e7 · 2026-05-19T11:37:53.000+02:00
diff --git a/ci/requirements-py3.10-min.yml b/ci/requirements-py3.10-min.yml
@@ -9,7 +9,6 @@ dependencies:
     - pytest-mock
     - pytest-timeout
     - python=3.10
-    - pytz
     - requests
     - pip:
         - h5py==3.6.0
diff --git a/ci/requirements-py3.10.yml b/ci/requirements-py3.10.yml
@@ -19,7 +19,6 @@ dependencies:
     - pytest-rerunfailures
     - conda-forge::pytest-remotedata  # version in default channel is old
     - python=3.10
-    - pytz
     - requests
     - scipy >= 1.7.2
     - statsmodels
diff --git a/ci/requirements-py3.11.yml b/ci/requirements-py3.11.yml
@@ -19,7 +19,6 @@ dependencies:
     - pytest-rerunfailures
     - conda-forge::pytest-remotedata  # version in default channel is old
     - python=3.11
-    - pytz
     - requests
     - scipy >= 1.7.2
     - statsmodels
diff --git a/ci/requirements-py3.12.yml b/ci/requirements-py3.12.yml
@@ -19,7 +19,6 @@ dependencies:
     - pytest-rerunfailures
     - conda-forge::pytest-remotedata  # version in default channel is old
     - python=3.12
-    - pytz
     - requests
     - scipy >= 1.7.2
     - statsmodels
diff --git a/ci/requirements-py3.13.yml b/ci/requirements-py3.13.yml
@@ -19,7 +19,6 @@ dependencies:
     - pytest-rerunfailures
     - conda-forge::pytest-remotedata  # version in default channel is old
     - python=3.13
-    - pytz
     - requests
     - scipy >= 1.7.2
     - statsmodels
diff --git a/ci/requirements-py3.14.yml b/ci/requirements-py3.14.yml
@@ -19,7 +19,6 @@ dependencies:
     - pytest-rerunfailures
     - conda-forge::pytest-remotedata  # version in default channel is old
     - python=3.14
-    - pytz
     - requests
     - scipy >= 1.7.2
     - statsmodels
diff --git a/docs/tutorials/solarposition.ipynb b/docs/tutorials/solarposition.ipynb
diff --git a/pvlib/iotools/pvgis.py b/pvlib/iotools/pvgis.py
@@ -20,7 +20,7 @@
 import requests
 import numpy as np
 import pandas as pd
-import pytz
+import zoneinfo
 from pvlib.iotools import read_epw
 
 URL = 'https://re.jrc.ec.europa.eu/api/'
@@ -413,10 +413,10 @@ def _coerce_and_roll_tmy(tmy_data, tz, year):
     re-interpreted as zero / UTC.
     """
     if tz:
-        tzname = pytz.timezone(f'Etc/GMT{-tz:+d}')
+        tzname = zoneinfo.ZoneInfo(f'Etc/GMT{-tz:+d}')
     else:
         tz = 0
-        tzname = pytz.timezone('UTC')
+        tzname = zoneinfo.ZoneInfo('UTC')
     new_index = pd.DatetimeIndex([
         timestamp.replace(year=year, tzinfo=tzname)
         for timestamp in tmy_data.index],
diff --git a/pvlib/location.py b/pvlib/location.py
@@ -6,10 +6,10 @@
 
 import pathlib
 import datetime
+import warnings
 import zoneinfo
 
 import pandas as pd
-import pytz
 import h5py
 
 from pvlib import solarposition, clearsky, atmosphere, irradiance
@@ -22,13 +22,11 @@ class Location:
     time zone, and altitude data associated with a particular geographic
     location. You can also assign a name to a location object.
 
-    Location objects have two time-zone attributes:
+    Location objects have a time-zone attribute:
 
         * ``tz`` is an IANA time-zone string.
-        * ``pytz`` is a pytz-based time-zone object (read only).
 
-    The read-only ``pytz`` attribute will stay in sync with any changes made
-    using ``tz``.
+       The ``pytz`` attribute was removed. Use ``tz`` property instead.
 
     Location objects support the print method.
 
@@ -47,8 +45,7 @@ class Location:
         list of valid name strings. An `int` or `float` must be a whole-number
         hour offsets from UTC that can be converted to the IANA-supported
         'Etc/GMT-N' format. (Note the limited range of the offset N and its
-        sign-change convention.) Time zones from the pytz and zoneinfo packages
-        may also be passed here, as they are subclasses of datetime.tzinfo.
+        sign-change convention.) Time zones from the zoneinfo packages may also be passed here.
 
         The `tz` attribute is represented as a valid IANA time zone name
         string.
@@ -118,7 +115,7 @@ def tz(self, tz_):
 
             self._zoneinfo = zoneinfo.ZoneInfo(f"Etc/GMT{-int(tz_):+d}")
         elif isinstance(tz_, datetime.tzinfo):
-            # Includes time zones generated by pytz and zoneinfo packages.
+            # Includes time zones generated by zoneinfo packages.
             self._zoneinfo = zoneinfo.ZoneInfo(str(tz_))
         else:
             raise TypeError(
@@ -127,11 +124,6 @@ def tz(self, tz_):
                 "datetime.tzinfo object (including subclasses)"
             )
 
-    @property
-    def pytz(self):
-        """The location's pytz time zone (read only)."""
-        return pytz.timezone(str(self._zoneinfo))
-
     @classmethod
     def from_tmy(cls, tmy_metadata, tmy_data=None, **kwargs):
         """
diff --git a/pvlib/solarposition.py b/pvlib/solarposition.py
@@ -1360,11 +1360,11 @@ def hour_angle(times, longitude, equation_of_time):
         Corresponding timestamps, must be localized to the timezone for the
         ``longitude``.
 
-        A `pytz.exceptions.AmbiguousTimeError` will be raised if any of the
-        given times are on a day when the local daylight savings transition
-        happens at midnight.  If you're working with such a timezone,
-        consider converting to a non-DST timezone (e.g. GMT-4) before
-        calling this function.
+        An error (AmbiguousTimeError in older pandas, ValueError in newer)
+        will be raised if any of the given times are on a day when the local
+        daylight savings transition happens at midnight.  If you're working
+        with such a timezone, consider converting to a non-DST timezone
+        (e.g. GMT-4) before calling this function.
     longitude : numeric
         Longitude in degrees
     equation_of_time : numeric
diff --git a/pvlib/tools.py b/pvlib/tools.py
@@ -4,11 +4,12 @@
 
 import contextlib
 import datetime as dt
+from datetime import timezone
 import warnings
 
 import numpy as np
 import pandas as pd
-import pytz
+import zoneinfo
 
 
 def cosd(angle):
@@ -135,8 +136,8 @@ def localize_to_utc(time, location):
     """
     if isinstance(time, dt.datetime):
         if time.tzinfo is None:
-            time = location.pytz.localize(time)
-        time_utc = time.astimezone(pytz.utc)
+            time = time.replace(tzinfo=location._zoneinfo)
+        time_utc = time.astimezone(timezone.utc)
     else:
         try:
             time_utc = time.tz_convert('UTC')
@@ -162,11 +163,11 @@ def datetime_to_djd(time):
     """
 
     if time.tzinfo is None:
-        time_utc = pytz.utc.localize(time)
+        time_utc = time.replace(tzinfo=timezone.utc)
     else:
-        time_utc = time.astimezone(pytz.utc)
+        time_utc = time.astimezone(timezone.utc)
 
-    djd_start = pytz.utc.localize(dt.datetime(1899, 12, 31, 12))
+    djd_start = dt.datetime(1899, 12, 31, 12, tzinfo=timezone.utc)
     djd = (time_utc - djd_start).total_seconds() * 1.0/(60 * 60 * 24)
 
     return djd
@@ -189,10 +190,10 @@ def djd_to_datetime(djd, tz='UTC'):
        The resultant datetime localized to tz
     """
 
-    djd_start = pytz.utc.localize(dt.datetime(1899, 12, 31, 12))
+    djd_start = dt.datetime(1899, 12, 31, 12, tzinfo=timezone.utc)
 
     utc_time = djd_start + dt.timedelta(days=djd)
-    return utc_time.astimezone(pytz.timezone(tz))
+    return utc_time.astimezone(zoneinfo.ZoneInfo(tz))
 
 
 def _pandas_to_doy(pd_object):
diff --git a/pyproject.toml b/pyproject.toml
@@ -13,7 +13,6 @@ requires-python = ">=3.10"
 dependencies = [
     'numpy >= 1.21.2',
     'pandas >= 1.3.3',
-    'pytz',
     'requests',
     'scipy >= 1.7.2',
     'h5py',
diff --git a/tests/iotools/test_midc.py b/tests/iotools/test_midc.py
@@ -1,6 +1,5 @@
 import pandas as pd
 import pytest
-import pytz
 
 from pvlib.iotools import midc
 from tests.conftest import TESTS_DATA_DIR, RERUNS, RERUNS_DELAY
diff --git a/tests/test_clearsky.py b/tests/test_clearsky.py
@@ -3,7 +3,7 @@
 import numpy as np
 from numpy import nan
 import pandas as pd
-import pytz
+import zoneinfo
 from scipy.linalg import hankel
 
 import pytest
@@ -770,7 +770,7 @@ def test_bird():
     times = pd.date_range(start='1/1/2015 0:00', end='12/31/2015 23:00',
                           freq='h')
     tz = -7  # test timezone
-    gmt_tz = pytz.timezone('Etc/GMT%+d' % -(tz))
+    gmt_tz = zoneinfo.ZoneInfo(f'Etc/GMT{-tz:+d}')
     times = times.tz_localize(gmt_tz)  # set timezone
     times_utc = times.tz_convert('UTC')
     # match test data from BIRD_08_16_2012.xls
diff --git a/tests/test_location.py b/tests/test_location.py
@@ -9,8 +9,6 @@
 
 import pytest
 
-import pytz
-
 import pvlib
 from pvlib import location
 from pvlib.location import Location, lookup_altitude
@@ -37,29 +35,26 @@ def test_location_all():
         pytest.param('Asia/Yangon', 'Asia/Yangon'),
         pytest.param(datetime.timezone.utc, 'UTC'),
         pytest.param(zoneinfo.ZoneInfo('Etc/GMT-7'), 'Etc/GMT-7'),
-        pytest.param(pytz.timezone('US/Arizona'), 'US/Arizona'),
+        pytest.param(zoneinfo.ZoneInfo('US/Arizona'), 'US/Arizona'),
         pytest.param(-6, 'Etc/GMT+6'),
         pytest.param(-11.0, 'Etc/GMT+11'),
         pytest.param(12, 'Etc/GMT-12'),
     ],
 )
 def test_location_tz(tz, tz_expected):
     loc = Location(32.2, -111, tz)
-    assert isinstance(loc.pytz, datetime.tzinfo)  # Abstract base class.
-    assert isinstance(loc.pytz, pytz.tzinfo.BaseTzInfo)
+    assert isinstance(loc._zoneinfo, datetime.tzinfo)  # Abstract base class.
     assert type(loc.tz) is str
     assert loc.tz == tz_expected
 
 
 def test_location_tz_update():
     loc = Location(32.2, -111, -11)
     assert loc.tz == 'Etc/GMT+11'
-    assert loc.pytz == pytz.timezone('Etc/GMT+11')  # Deprecated attribute.
 
     # Updating Location's tz updates read-only time-zone attributes.
     loc.tz = 7
     assert loc.tz == 'Etc/GMT-7'
-    assert loc.pytz == pytz.timezone('Etc/GMT-7')  # Deprecated attribute.
 
 
 @pytest.mark.parametrize(
@@ -99,8 +94,8 @@ def test_location_print_all():
     assert tus.__str__() == expected_str
 
 
-def test_location_print_pytz():
-    tus = Location(32.2, -111, pytz.timezone('US/Arizona'), 700, 'Tucson')
+def test_location_print():
+    tus = Location(32.2, -111, zoneinfo.ZoneInfo('US/Arizona'), 700, 'Tucson')
     expected_str = '\n'.join([
         'Location: ',
         '  name: Tucson',
diff --git a/tests/test_solarposition.py b/tests/test_solarposition.py
@@ -1,21 +1,21 @@
 import calendar
 import datetime
+import math
 import warnings
+import zoneinfo
+from datetime import timezone
 
 import numpy as np
 import pandas as pd
-
-from .conftest import assert_frame_equal, assert_series_equal
-from numpy.testing import assert_allclose
 import pytest
 import pytz
+from numpy.testing import assert_allclose
 
-from pvlib.location import Location
 from pvlib import solarposition, spa
+from pvlib.location import Location
 
-from .conftest import (
-    requires_ephem, requires_spa_c, requires_numba, requires_pandas_2_0
-)
+from .conftest import (assert_frame_equal, assert_series_equal, requires_ephem,
+                       requires_numba, requires_pandas_2_0, requires_spa_c)
 
 # setup times and locations to be tested.
 times = pd.date_range(start=datetime.datetime(2014, 6, 24),
@@ -343,29 +343,26 @@ def test_pyephem_physical_dst(expected_solpos, golden):
 
 @requires_ephem
 def test_calc_time():
-    import pytz
-    import math
     # validation from USNO solar position calculator online
 
-    epoch = datetime.datetime(1970, 1, 1)
-    epoch_dt = pytz.utc.localize(epoch)
+    epoch = datetime.datetime(1970, 1, 1, tzinfo=timezone.utc)
 
     loc = tus
     loc.pressure = 0
-    actual_time = pytz.timezone(loc.tz).localize(
-        datetime.datetime(2014, 10, 10, 8, 30))
-    lb = pytz.timezone(loc.tz).localize(datetime.datetime(2014, 10, 10, tol))
-    ub = pytz.timezone(loc.tz).localize(datetime.datetime(2014, 10, 10, 10))
+    tz = zoneinfo.ZoneInfo(loc.tz)
+    actual_time = datetime.datetime(2014, 10, 10, 8, 30, tzinfo=tz)
+    lb = datetime.datetime(2014, 10, 10, tol, tzinfo=tz)
+    ub = datetime.datetime(2014, 10, 10, 10, tzinfo=tz)
     alt = solarposition.calc_time(lb, ub, loc.latitude, loc.longitude,
                                   'alt', math.radians(24.7))
     az = solarposition.calc_time(lb, ub, loc.latitude, loc.longitude,
                                  'az', math.radians(116.3))
-    actual_timestamp = (actual_time - epoch_dt).total_seconds()
+    actual_timestamp = (actual_time - epoch).total_seconds()
 
     assert_allclose((alt.replace(second=0, microsecond=0) -
-                     epoch_dt).total_seconds(), actual_timestamp)
+                     epoch).total_seconds(), actual_timestamp)
     assert_allclose((az.replace(second=0, microsecond=0) -
-                     epoch_dt).total_seconds(), actual_timestamp)
+                     epoch).total_seconds(), actual_timestamp)
 
 
 @requires_ephem
