Install & Compatibility
Where this runs
tested against v1.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 30.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.000s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_tz
✓ from tzfpy import get_tz
Primary function to get a single timezone name for coordinates.
get_tzs
✓ from tzfpy import get_tzs
Function to get all possible timezone names for coordinates, useful near borders.
get_tz_polygon_geojson
✓ from tzfpy import get_tz_polygon_geojson
For data visualization, retrieves GeoJSON polygon data for a given timezone.
get_tz_index_geojson
✓ from tzfpy import get_tz_index_geojson
For data visualization, retrieves GeoJSON index data for a given timezone.
This quickstart demonstrates how to retrieve a timezone name for given coordinates using `tzfpy.get_tz` and then apply it to a `datetime` object using Python's standard `zoneinfo` module. It is recommended to install `tzfpy` with the `tzdata` extra for optimal `zoneinfo` compatibility.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
from tzfpy import get_tz
# Example coordinates for Tokyo, Japan
longitude = 139.7744
latitude = 35.6812
# Get the timezone name from coordinates
tz_name = get_tz(longitude, latitude)
print(f"Timezone for ({longitude}, {latitude}): {tz_name}")
# Use the timezone name with Python's built-in zoneinfo for datetime objects
if tz_name:
try:
tokyo_tz = ZoneInfo(tz_name)
now_utc = datetime.now(timezone.utc)
now_local = now_utc.replace(tzinfo=tokyo_tz)
print(f"Current UTC time: {now_utc}")
print(f"Current local time in {tz_name}: {now_local}")
except Exception as e:
print(f"Error creating ZoneInfo object for '{tz_name}': {e}")
else:
print(f"Could not determine timezone for ({longitude}, {latitude})")
Debug
Known issues
gotchatzfpy uses simplified polygon data for speed, which means its accuracy may be reduced, especially around timezone borders. For applications requiring extremely high precision near boundaries, alternatives like `timezonefinder` might be more suitable, though potentially slower.fixBe aware of this trade-off. For higher precision, consider `timezonefinder`. For general use, `tzfpy` provides excellent performance.
affects: All versions
gotchaThe underlying Rust implementation uses lazy initialization. This means the very first call to `get_tz` or `get_tzs` will be slower than subsequent calls as the data structures are loaded into memory.fixIf latency on the very first call is critical, consider making a dummy call during application startup to pre-load the data (e.g., `get_tz(0, 0)`).
affects: All versions
gotchaThe library utilizes approximately 40MB of memory for its internal data structures. While efficient for its task, this should be considered in memory-constrained environments.fixFactor the 40MB memory footprint into your application's resource planning.
affects: All versions
gotchaNew timezone names added to `tzfpy` might be incompatible with older versions of timezone packages like `pytz` or system `tzdata`. The recommended approach is to install `tzfpy` with the `[tzdata]` extra and use Python's built-in `zoneinfo` module.fixAlways install `tzfpy` using `pip install "tzfpy[tzdata]"` and utilize `from zoneinfo import ZoneInfo` for robust timezone handling.
affects: All versions, especially when mixing with older timezone libraries
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tzfpy'
The 'tzfpy' package has not been installed in the Python environment where the code is being run.
ImportError: cannot import name 'tz_lookup' from 'tzfpy'
The 'tz_lookup' function is a method of the 'TZFinder' class, not a top-level function directly importable from the 'tzfpy' module.
fixfrom tzfpy import TZFinder
t = TZFinder()
timezone = t.tz_lookup(lon, lat)
AttributeError: module 'tzfpy' has no attribute 'tz_lookup'
The 'tz_lookup' method needs to be called on an instantiated object of the 'TZFinder' class, not directly on the 'tzfpy' module itself.
fixfrom tzfpy import TZFinder
t = TZFinder()
timezone = t.tz_lookup(lon, lat)
TypeError: Argument 'lon' must be float, not str
The 'tz_lookup' method expects float values for longitude and latitude, but an argument of an incorrect type (e.g., string, integer without explicit conversion) was provided.
fixtimezone = t.tz_lookup(float(longitude_value), float(latitude_value))
Upgrade
Version history
1.3.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
tzdataoptionalRecommended for best practices when handling timezone objects with Python's built-in `zoneinfo` module.
pytzoptionalOptional dependency for compatibility with older timezone handling libraries, though `tzdata` with `zoneinfo` is generally preferred.