Skip to content

Arrow

Developer UtilitiesDate & TimePython
Official docs ↗GitHub ↗

What it is

Arrow is a Python library that provides a sensible, human-friendly approach to creating, manipulating, formatting, and converting dates and times. It simplifies working with time zones and datetime arithmetic.

Arrow allows you to create datetime objects, shift them by time intervals, convert between time zones, format and parse strings, and perform human-readable operations.

Installation

pip install arrow

Getting started

The smallest useful thing you can do with it, and what each part means.

Getting the current time
import arrow
now = arrow.now()
print(now)
Retrieves the current local time as an Arrow object.
Creating a specific datetime
import arrow
dt = arrow.get('2025-08-21 15:30', 'YYYY-MM-DD HH:mm')
print(dt)
Parses a string to create a specific datetime using a format string.
Shifting time
import arrow
now = arrow.now()
future = now.shift(days=+5, hours=+3)
print(future)
Shifts the datetime forward by 5 days and 3 hours.

Advanced usage

Where the library earns its place over a simpler alternative.

Time zone conversion
import arrow
now = arrow.now('UTC')
ny = now.to('America/New_York')
print(ny)
Converts a UTC datetime to another timezone, e.g., New York.
Formatting dates
import arrow
now = arrow.now()
print(now.format('YYYY-MM-DD HH:mm:ss'))
Formats the Arrow object into a human-readable string.
Humanized differences
import arrow
past = arrow.get('2025-08-01')
now = arrow.now()
print(past.humanize(now))
Shows the difference between two datetimes in a human-friendly way, e.g., '3 weeks ago'.
Parsing and formatting multiple formats
import arrow
dt = arrow.get('21/08/2025', 'DD/MM/YYYY')
print(dt.format('YYYY-MM-DD'))
Parses a date string with a custom format and converts it into another format.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

ParserError
Ensure the input string matches the provided format string when parsing.
ValueError
Check that date and time components are valid and within acceptable ranges.

Best practices

  • Use Arrow objects instead of Python datetime objects for simplicity and readability.
  • Always specify a timezone when working with global applications.
  • Use humanize for user-friendly time displays.
  • Prefer `shift()` over manual datetime arithmetic.
  • Use Arrow for parsing, formatting, and conversion to reduce boilerplate code.

Background

Why it exists, and what it was reacting to.

Arrow was created by Chris Smith to address the limitations of Python's standard `datetime` module. It focuses on simplicity, readability, and human-friendly operations, enabling developers to handle date and time in an intuitive manner.

Related libraries

Others in Developer Utilities for Python.

← All Python librariesPython guide