---
id: datefinder
version: "1.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# datefinder — Extract datetime objects from natural language text

License: permissive · Maintenance: active · Downloads: 4.5M/mo

## What it is and what it does

Datefinder is a Python date parser designed to extract date and time expressions from unstructured text. It handles explicit calendar dates (e.g., "January 4th, 2017" or "2024-11-03 18:00"), relative expressions ("tomorrow", "in 3 days"), and multiple date formats in a single pass. The package provides two main APIs: a compatibility layer that returns datetime objects, and a modern typed API that returns match objects with kind, text span, confidence, and structured values.

The package is useful for processing emails, contracts, logs, scraped HTML, and other mixed-format documents where dates are embedded in natural language. It includes a command-line interface for shell pipelines and supports anchoring relative date parsing to a reference date. As of version 1.0.0, the default engine uses a v2 compatibility implementation backed by Rust, with the original engine available as a fallback.

Use it for:

- Extract dates from email threads, support tickets, or conversation logs to organize or filter by date
- Parse contract or legal document dates to identify key deadlines and effective dates
- Find and normalize dates in scraped web content or mixed-format reports for data pipeline ingestion
- Process relative date expressions in user input (e.g., "due tomorrow") anchored to a specific reference date
- Migrate legacy date extraction code by using find_dates_legacy() for parity, then switching to the modern API

## Worth the install?

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

Datefinder extracts date and time expressions from unstructured text and converts them into datetime objects or typed match objects with confidence and span information.

Yes, if you need to extract dates from unstructured text. The package is actively maintained, has no known vulnerabilities, and supports current Python versions. Install friction is moderate due to Rust compilation on unsupported platforms, but prebuilt wheels cover common targets. The MIT license is permissive. Consider it essential for document processing, log analysis, or data normalization tasks involving natural language dates.

## Install

pip install datefinder
uv add datefinder
poetry add datefinder

## Installing datefinder

Before you install: Medium install friction due to Rust compilation requirement when prebuilt wheels are unavailable. The package is actively maintained with recent releases and provides prebuilt wheels for common platforms (Linux glibc/musl, macOS, Windows). Requires Python 3.9+.

License in practice: MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install datefinder

import datefinder
from datetime import datetime, timezone

text = "Meeting tomorrow; launch on 2024-11-03 18:00 UTC."
ref = datetime(2026, 3, 19, 12, 0, tzinfo=timezone.utc)

for match in datefinder.find_dates(text, base_date=ref):
    print(match)

Requires Python 3.9+. If a prebuilt wheel is unavailable for your platform, pip will build from source and requires a Rust toolchain.

Verify before relying:

- Accuracy and coverage of date extraction compared to alternatives like dateparser or Duckling
- Performance characteristics on very large documents or high-volume batch processing
- Behavior differences between v2 (default) and legacy engines for edge cases in your use case

## Package facts

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

## Tags

extract dates from text, parse natural language dates, find dates in documents, date extraction library, temporal expression parsing, relative date parsing, text date recognition, date-extraction, nlp, text-parsing

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