---
id: cftime
version: "1.6.5"
license: MIT
license_treatment: permissive
maintenance: aging
---

# cftime — Time-handling functionality from netcdf4-python

License: permissive · Maintenance: aging · Downloads: 4.8M/mo

## What it is and what it does

cftime is a time-handling library extracted from netcdf4-python that specializes in converting between calendar dates and numeric time values for scientific data. It handles non-standard calendars like 360-day calendars used in climate models and real-world calendars with support for astronomical year numbering, including year zero. The package is built around two core functions: num2date converts numeric time values into cftime.datetime objects, and date2num does the reverse. It depends only on numpy.

The library is commonly used in climate science, weather modeling, and geophysical data processing where time must be represented in non-Gregorian or extended calendars. It provides a cftime.datetime class that mimics Python's standard datetime but extends it with calendar awareness and methods like toordinal, fromordinal, and change_calendar for switching between calendar systems. The package has been maintained since its first release in 2018, with recent versions adding support for modern Python versions.

Use it for:

- Parse and convert NetCDF time coordinates in climate and weather datasets where non-standard calendars are used.
- Convert between 'days since' or 'seconds since' reference dates and human-readable dates for scientific data analysis.
- Handle astronomical year numbering and year-zero conventions in historical or extended-range climate simulations.
- Index and subset time-series data by converting date ranges to numeric time indices.
- Ensure consistent time representation across datasets with different calendar conventions in multi-model comparisons.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts between calendar dates and numeric time values for non-standard and real-world calendars, with support for astronomical year numbering and multiple calendar systems.

Yes. cftime is a stable, actively maintained library with no known vulnerabilities, permissive MIT licensing, and wide adoption in scientific computing (top 5000 PyPI packages). Install friction is moderate but well-mitigated by prebuilt wheels for all major platforms and Python versions. It is essential for anyone working with climate data, NetCDF files, or non-Gregorian calendars.

## Install

pip install cftime
uv add cftime
poetry add cftime

## Installing cftime

Before you install: Medium install friction due to compiled wheels; prebuilt binaries available for Python 3.10–3.14 on macOS, Linux, Windows, and ARM platforms. Last release 305 days ago; maintenance status is aging but the package is marked Production/Stable.

License in practice: MIT license is permissive; no restrictions on commercial or private use, modification, or redistribution as long as the license and copyright notice are included.

Quickstart:

pip install cftime
import cftime
import numpy

# Convert numeric time to datetime
times = cftime.num2date([0, 1, 2], units='days since reference', calendar='standard')

# Convert datetime back to numeric
nums = cftime.date2num(times, units='days since reference', calendar='standard')

Requires numpy; Python 3.10 or later.

Verify before relying:

- Specific calendar systems supported beyond 'standard', 'gregorian', 'julian', 'proleptic_gregorian', '360_day', 'noleap', '365_day'.
- Whether performance improvements from earlier releases remain current in version 1.6.5.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 4.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

calendar date to numeric time conversion, cftime datetime handling, netcdf time units parsing, non-standard calendar support, num2date date2num, astronomical year numbering, climate data time handling, climate-data, time-handling, netcdf

[View on SkillFed](https://skillfed.io/packages/cftime) · [View on PyPI](https://pypi.org/project/cftime/)