tzclock

A small live timezone converter for the terminal. Reads your system clock and shows local time alongside a selected timezone, including the date, UTC offset, and date difference. No network requests during use.

Install

Requires Python 3.9 or newer. Once published to PyPI:

python -m pip install tzclock-cli
tzclock

Use python3 on macOS/Linux or py on Windows if that is your Python launcher. For an isolated command-line installation, pipx install tzclock-cli also works if you already use pipx. In a conda environment, activate it and use the same pip command; a separate conda package is not required.

Before publication, install a supplied wheel:

python -m pip install ./dist/tzclock_cli-0.1.0-py3-none-any.whl

Pip creates the tzclock launcher, including an executable launcher on Windows. If your Python scripts directory is not on PATH, use python -m tzclock instead. No copying into system directories or manually setting executable permissions.

Use

tzclock
tzclock --zone Asia/Seoul
tzclock --zone Asia/Seoul --once
tzclock --version
python -m tzclock --zone Europe/Warsaw --once

During search, Q is a normal letter; press Esc then Q to quit. Ctrl+C also exits. Quick choices include Warsaw, Seoul, Taipei, Hong Kong, Tokyo and UTC. The menu needs at least 48 columns by 16 rows. Resize the terminal if prompted. Redirected output automatically uses the one-shot text mode.

Platform handling

Dependencies are declared in pyproject.toml, not installed by application code:

dependencies = [
  "tzdata",
  "windows-curses>=2.4; sys_platform == 'win32'",
]

Pip installs windows-curses only on Windows. macOS and Linux use their Python build's standard curses module. The small tzdata package is installed on all platforms as a fallback when no system timezone database is available. Python's zoneinfo normally uses system timezone data first. DST rules come from that database; keep your system and dependencies updated.

Interactive Windows support depends on a windows-curses wheel being available for your Python version and architecture. Conventional CPython installations are the intended target; not every Python implementation or platform is promised. On minimal Unix Python builds without curses, use --once or a Python build with curses support. No administrator privileges are needed inside a virtual environment.

If you previously copied a standalone tzclock into /usr/local/bin, that old file may take precedence. Check command -v tzclock (Windows: where tzclock). Use python -m tzclock --version to verify the installed package directly.

Development

python -m pip install -e .
python -m unittest discover -s tests -v

See PUBLISH.md for the short release procedure. MIT licensed.