Analog Clock v1.6.0

Analog Clock is a terminal-based analog clock rendered with Python's curses module. It draws an analog clock face, hour, minute, and optional second hands, along with a digital time readout.

The digital readout is timezone-aware: it shows any IANA timezone, follows daylight saving automatically, and labels itself with the zone's abbreviation (or a numeric UTC offset for zones that don't have one). A date line is drawn beneath it in one of three selectable styles, stepping down to a narrower style automatically if the terminal is too small for the requested one. Both the timezone label and the date line can be turned off individually.

The clock face fits itself to the current terminal size, redraws on resize, and shows a clear message rather than breaking if the window is too small. --once and --snapshot render a single frame for scripted checks and clean screenshots, respectively. Color is optional, off by default, and available through six --theme choices.

See CHANGELOG.md for release history.

Requirements

• Python 3.9 or newer
• A terminal that supports curses

The clock uses Python's standard-library zoneinfo module for timezone-aware local time.

On Windows, two additional packages are required (Linux/macOS already provide these via the OS):

pip install windows-curses tzdata

Project layout

The program is split across three files, all of which must be kept together in the same directory:

analog_clock.py   Entry point: curses drawing and the redraw loop
cli.py             Argument parsing and configuration
clock_core.py       Geometry, layout, and time formatting (no curses dependency)

Run the clock via analog_clock.py; the other two files are imported automatically and are not meant to be run directly.

Timezone

By default, the clock displays time for the America/New_York timezone. Use --timezone or -z with any valid IANA timezone name to display a different timezone:

python3 analog_clock.py --timezone America/Chicago

This lets Python handle daylight saving time and standard time automatically.

The digital readout shows the zone's abbreviation after the time, so --timezone Europe/London reads 14:30:00 BST in summer and 14:30:00 GMT in winter. Zones that have no lettered abbreviation show a numeric UTC offset instead, for example +0545 for Asia/Kathmandu. Use --no-timezone to hide it.

Run

python3 analog_clock.py

Options

-z, --timezone IANA_NAME   Timezone to display (default: America/New_York)
-r, --refresh-rate SECONDS Seconds between redraws (default: 1)
--radius CELLS             Clock radius in terminal columns
                           (minimum: 5; default: fit to terminal)
--no-seconds               Hide seconds from the analog and digital displays
--no-digital               Hide the digital readout (time and date)
--no-date                  Hide the date line beneath the digital readout
--no-timezone              Hide the timezone abbreviation after the time
--no-border                Hide the terminal border
--format {12,24}           Digital clock format (default: 24)
--date-format {long,short,iso}
                           Date line style (default: long)
--theme {mono,matrix,amber,ice,virtual-boy,blue}
                           Color theme (default: mono, i.e. no override)
--no-color                 Disable color even if --theme requested one
--once                     Render a single frame and exit immediately
                           (for testing)
--snapshot                 Render a single frame and wait for a keypress
                           before exiting (for screenshots)
--version                  Show the program version

Examples:

python3 analog_clock.py --timezone Europe/London --format 12
python3 analog_clock.py --refresh-rate 0.25 --radius 18 --no-border
python3 analog_clock.py --format 12 --no-seconds
python3 analog_clock.py --no-border --no-digital
python3 analog_clock.py --once
python3 analog_clock.py --snapshot --no-border --radius 20
python3 analog_clock.py --date-format iso --no-timezone
python3 analog_clock.py --no-date --radius 12
python3 analog_clock.py --theme matrix
python3 analog_clock.py --theme amber --no-color

Date line

A date line is drawn beneath the digital time. Three styles are available through --date-format:

long    Friday, July 24, 2026   (default)
short   Fri Jul 24
iso     2026-07-24

The requested style is a preference rather than a demand. If it is wider than the terminal, the clock falls back to the next narrower style instead of clipping the date mid-word.

Because the date adds a second row to the digital readout, the clock face is fitted one row smaller when it is shown. Use --no-date to hide the date and return the row to the clock face; --no-digital hides the time and date together.

Color themes

Color is off by default and never changes anything unless --theme is used. Six themes are available:

mono         No color override -- the terminal's own colors (default)
matrix       Green, flat and uniform
amber        Amber, with brighter hands
ice          Cyan, with brighter hands
virtual-boy  Red, with brighter hands
blue         Blue, with brighter hands

Every color theme forces the darkest black the terminal has for its background, regardless of how the terminal itself is themed -- so matrix gets a true black background even in a terminal set up with, say, a dark blue or gray one. matrix is deliberately a single flat color throughout; every other theme renders the hands brighter than the face and border for a bit of depth, using the terminal's bold-as-bright rendering rather than a second color.

--no-color disables color even when --theme requested one, and color is also disabled automatically when the NO_COLOR environment variable is set (see no-color.org) -- both take priority over --theme no matter what order the flags are given in. Color is also skipped, without error, on any terminal that doesn't actually support it.

Screenshots

All captures below were taken with --snapshot, so they show the exact rendered frame with no mid-capture drift.

Full-size terminal

--date-format short	--date-format iso	--no-seconds

Compact terminal

A smaller window forces the clock face down to a smaller radius, fitted automatically to the available space.

Default	--no-date	--no-timezone

Color themes

--theme matrix	--theme amber	--theme ice

--theme virtual-boy	--theme blue

Responsive sizing

By default, the clock uses the largest radius that safely fits inside the current terminal window.

A radius supplied with --radius is treated as the preferred size. If the requested radius is larger than the available terminal space, the clock reduces it to the largest size that fits.

The minimum supported radius is 5. If the terminal cannot fit a clock at that size, the program displays Terminal too small. Enlarging the terminal causes the clock to return automatically.

Controls

• Press q or Q to quit.
• Press Ctrl-C to interrupt from the terminal.
• Resize the terminal to recalculate and redraw the clock layout.

Notes

The clock face accounts for terminal cell proportions by scaling vertical distances, which helps the clock appear circular in typical terminal fonts.

Terminal drawing operations are clipped to the available window's bounds to prevent ordinary edge and resize conditions from crashing the display.

The refresh interval is measured with Python's monotonic clock so elapsed-time measurement is not affected by changes to the system wall clock.