Arrow: Better Dates & Times for Python

1.4.0 · active · verified Mon Apr 06

Arrow is a Python library that offers a sensible, human-friendly approach to dates, times, and timestamps. It aims to be a drop-in replacement for the `datetime` module, providing a more convenient API for creating, manipulating, formatting, and converting dates and times, including robust timezone handling and humanization. The current version is 1.4.0, and it maintains an active release cadence, with updates typically occurring every few months.

Common errors

```
ImportError: No module named arrow
```
cause The 'arrow' library is not installed in the Python environment.

fix Install the 'arrow' library using pip: 'pip install arrow'.
```
AttributeError: 'Arrow' object has no attribute 'timestamp'
```
cause The 'Arrow' object does not have a 'timestamp' method; 'timestamp' is an attribute.

fix Access the 'timestamp' attribute directly: 'arrow_object.timestamp'.
```
AttributeError: 'Arrow' object has no attribute 'strftime'
```
cause The 'Arrow' object does not have a 'strftime' method; it uses 'format' for formatting.

fix Use the 'format' method: 'arrow_object.format('YYYY-MM-DD')'.
```
TypeError: fromtimestamp() argument must be int or float, not str
```
cause Passing a string to 'arrow.get()' without specifying the format leads to this error.

fix Specify the format when parsing a string: 'arrow.get('2023-04-15', 'YYYY-MM-DD')'.
```
ValueError: Invalid format string
```
cause Using an incorrect or unsupported format string with the 'format' method.

fix Ensure the format string follows Arrow's formatting tokens: 'arrow_object.format('YYYY-MM-DD')'.

Warnings

breaking Arrow dropped support for Python 3.6 and 3.7 starting with version 1.3.0. Users on these Python versions must upgrade their Python environment to 3.8 or newer to use Arrow 1.3.0+.
Fix: Upgrade Python to version 3.8 or higher. Alternatively, pin Arrow to a version less than 1.3.0 if Python upgrade is not feasible (e.g., `pip install 'arrow<1.3.0'`).
gotcha Prior to version 1.1.1, explicit `tzinfo` arguments to `arrow.get()` might not have been properly respected in all cases, potentially leading to incorrect timezone awareness for parsed dates.
Fix: Ensure you are using Arrow version 1.1.1 or higher for reliable `tzinfo` handling with `arrow.get()`. Always verify the timezone of your `Arrow` object using `.tzinfo`.
gotcha Arrow objects are not direct subclasses of Python's built-in `datetime.datetime` objects. While they offer a similar interface, direct compatibility with libraries expecting `datetime.datetime` might require explicit conversion using the `.datetime` property.
Fix: When interfacing with other libraries that strictly require `datetime.datetime` objects, convert your `Arrow` object using `my_arrow_obj.datetime`.
gotcha Just like standard `datetime`, `arrow` can create timezone-naive objects if no timezone information is provided during creation or parsing. Operations involving naive and aware objects can lead to `TypeError` or incorrect results.
Fix: Whenever possible, prefer creating timezone-aware `Arrow` objects (e.g., `arrow.utcnow()`, `arrow.now(tz='America/New_York')`, or parsing strings with explicit offsets). Use `.to('timezone')` to convert between timezones safely.

Install

pip install arrow Install stable version

Imports

arrow
```
import arrow
```

Quickstart

This quickstart demonstrates how to get current times, parse date strings, format Arrow objects, perform time shifts, and humanize time differences.

import arrow

# Get current UTC time
now_utc = arrow.utcnow()
print(f"Current UTC: {now_utc}")

# Get current local time
now_local = arrow.now()
print(f"Current Local: {now_local}")

# Parse a string into an Arrow object
dt_string = '2023-10-27T10:30:00-05:00'
dt_obj = arrow.get(dt_string)
print(f"Parsed datetime: {dt_obj}")

# Format an Arrow object
formatted_dt = dt_obj.format('YYYY-MM-DD HH:mm:ss ZZ')
print(f"Formatted datetime: {formatted_dt}")

# Shift an Arrow object
tomorrow = now_local.shift(days=+1)
yesterday = now_local.shift(days=-1)
print(f"Tomorrow: {tomorrow}")
print(f"Yesterday: {yesterday}")

# Humanize an Arrow object
humanized_diff = tomorrow.humanize(now_local)
print(f"Tomorrow relative to now: {humanized_diff}")

view raw JSON →