Install & Compatibility
Where this runs
tested against v1.6.5 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.256s · 95MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.266s · 93MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
datetime
✓ from cftime import datetime
num2date
✓ from cftime import num2date
date2num
✓ from cftime import date2num
num2pydate
✓ from cftime import num2pydate
✗ from cftime import num2date; # if expecting python datetime objects
num2date now returns cftime.datetime by default since v1.1.0; use num2pydate for native python datetime objects.
This quickstart demonstrates how to create `cftime.datetime` objects, convert them to numeric representations using `date2num`, and convert numeric times back to `cftime.datetime` objects using `num2date`, showcasing different calendar types.
import cftime
import numpy as np
# Create a cftime.datetime object with a specific calendar
date_obj = cftime.datetime(2000, 2, 29, 12, 0, 0, calendar='gregorian')
print(f"Created cftime.datetime (Gregorian): {date_obj}")
# Convert to a numeric representation (e.g., 'days since 2000-01-01')
units = "days since 2000-01-01"
numeric_time = cftime.date2num(date_obj, units=units, calendar=date_obj.calendar)
print(f"Numeric time ({units}): {numeric_time}")
# Convert back to a cftime.datetime object
reconstructed_date = cftime.num2date(numeric_time, units=units, calendar=date_obj.calendar)
print(f"Reconstructed cftime.datetime: {reconstructed_date}")
# Example with a non-standard calendar (360_day has Feb 30)
date_360_day = cftime.datetime(2000, 2, 30, calendar='360_day')
print(f"360-day calendar date: {date_360_day}")
Debug
Known issues
breakingSince `cftime` v1.1.0, `cftime.num2date` defaults to returning `cftime.datetime` instances for all calendars. Previously, it would return standard `python datetime` objects when possible.fixIf you require standard `python datetime` objects, use the `cftime.num2pydate` function instead. Otherwise, update your code to expect `cftime.datetime` objects.
affects: >=1.1.0
breakingIn `cftime` v1.2.0, the default `calendar` argument for `cftime.date2num` changed from `'standard'` to `None`. This means the calendar is now inferred from the input `datetime` object(s).fixAlways explicitly specify the `calendar` argument in `cftime.date2num` calls to ensure consistent behavior, e.g., `cftime.date2num(dates, units, calendar='gregorian')`.
affects: >=1.2.0
breakingThe legacy functions `cftime.utime`, `cftime.JulianDayFromDate`, and `cftime.DateFromJulianDay` were removed in v1.5.0.fixReplace usage of `JulianDayFromDate` and `DateFromJulianFromDate` with `cftime.datetime.toordinal` and `cftime.datetime.fromordinal` respectively. `cftime.utime` no longer has a direct replacement and refactoring may be needed based on its specific usage.
affects: >=1.5.0
deprecatedThe direct use of calendar-specific subclasses (e.g., `cftime.DatetimeNoLeap`) in operations like `cftime.num2date`, `cftime.datetime.__add__`, and `cftime.datetime.__sub__` is deprecated and will be removed in a future release.fixPrefer using the base `cftime.datetime` class with the `calendar` keyword argument, e.g., `cftime.datetime(2000, 1, 1, calendar='noleap')`.
affects: >=1.4.1 (deprecation started)
gotchaPerformance may degrade when performing calculations with `cftime.datetime` instances that represent dates extremely far from the 1970-01-01 reference date. This is due to the complex leap year calculations across various supported calendars.fixBe mindful of performance for very distant dates. For highly performance-sensitive applications with extreme date ranges, consider profiling and optimizing accordingly, or ensuring your time 'units' define an origin closer to your data range.
affects: All versions
gotchaThe 'standard' calendar explicitly marks dates between October 5 and October 14, 1582, as invalid. These dates are skipped to account for the historical Julian-to-Gregorian calendar transition.fixIf working with historical dates that span or predate this transition and require continuous date representation (e.g., for modeling without a break), use the 'proleptic_gregorian' calendar which applies the Gregorian rules universally and avoids this gap.
affects: All versions
Errors
Common errors & fixes
Failed building wheel for cftime
This error typically occurs during installation on Linux systems when the required C/C++ compilers (like gcc) and Python development headers are missing, which are necessary to compile `cftime`'s C extensions.
fixInstall the necessary build tools and Python development headers. For Debian/Ubuntu-based systems: `sudo apt-get update && sudo apt-get install python3-dev gcc`. For systems using Anaconda/Miniconda, use `conda install cftime` which provides pre-compiled binaries.
TypeError: unsupported operand type(s) for +: 'cftime._cftime.DatetimeNoLeap' and 'datetime.timedelta'
Direct arithmetic operations with `datetime.timedelta` are not universally supported by all `cftime.datetime` calendar types, especially non-standard ones, as `datetime.timedelta` assumes a standard Gregorian-like calendar system. The `cftime.datetime` instances are calendar-aware and require specific methods for time arithmetic.
fixFor standard calendar types, ensure the `cftime.datetime` object is calendar-aware and try `cftime.datetime`'s own arithmetic or conversion methods. For non-standard calendars, it's often best to convert the `cftime.datetime` object to a numerical representation (e.g., days/seconds since an epoch) for arithmetic operations, and then convert back to a `cftime.datetime` object.
TypeError: <class 'cftime._cftime.Datetime360Day'> is not convertible to datetime
Python's native `datetime.datetime` objects only support standard Gregorian and Julian calendars. `cftime.datetime` instances representing non-standard calendars (like '360_day', 'noleap', '365_day') cannot be directly converted to `datetime.datetime` because the native Python object lacks the capability to represent these calendar systems.
fixIf a native `datetime.datetime` object is absolutely required, you must first convert the `cftime.datetime` object to a compatible calendar (e.g., 'standard' or 'proleptic_gregorian') if the conversion is meaningful for your data, or manually extract its components (year, month, day, etc.) and handle them separately. The `cftime.num2pydate` function can convert `cftime.datetime` objects to Python `datetime` objects if the calendar is compatible.
ValueError: given calendar 'invalid_calendar_name' is not a supported calendar
This error occurs when the `calendar` argument provided to `cftime.datetime` or related functions does not match one of the predefined and supported CF-compliant calendar strings.
fixUse one of the valid CF-compliant calendar strings. The supported calendars are: `'standard'`, `'gregorian'`, `'proleptic_gregorian'`, `'noleap'`, `'365_day'`, `'360_day'`, `'julian'`, `'all_leap'`, `'366_day'`.
Upgrade
Version history
1.6.5latest on PyPI · released Oct 13, 2025
Audit
Dependencies
numpyrequiredRequired for array operations and core date/time representations.
CythonoptionalUsed for compiling performance-critical C extensions; required for building from source.