pychron

pychron is a small command-line tool that shows, live in the terminal, how long a Python script has been running. It keeps a counter ticking second by second on the bottom line without breaking the script's own output. When the script finishes, it prints the start time, the finish time and the total duration as a summary. I developed it in early 2026 and published it on PyPI.

Purpose

Scripts that move data, run batch jobs or do maintenance work can run for minutes or even hours. During that time they may print nothing for a long while, which makes it hard to tell whether the script is stuck. I also did not want to add timing code inside a script every time I needed to know how long a job took. I wrote pychron so I could run any script without changing it at all and still see its duration.

How it works

I call the tool as pychron main.py. Every argument written after the script name is passed to the script unchanged. pychron starts the script as a separate process using the same Python interpreter that runs pychron itself. It passes the -u flag to the interpreter, which makes output flow through immediately instead of waiting in a buffer. The script's standard output and error output are merged into a single stream.

At the same time a background thread runs. Every second, this thread rewrites the same line with the current time and the number of seconds since the start. When a new line arrives from the script, pychron first clears the counter line, prints the script's line, and the counter carries on at the next second. To stop the two threads from writing to the terminal at the same moment, writes are queued behind a lock. This keeps the script's output and the counter from getting mixed up.

When the script ends, the counter stops and the finish time and total duration in seconds are printed.

Key features

• It shows the elapsed time in real time while the script runs.
• It does not hide or break the script's own output.
• It prints the start time, finish time and total duration on separate lines.
• It marks its output with ANSI color codes; lines from pychron start with a red prefix, so they are easy to tell apart from the script's output.
• When run without a script name, it prints a short message explaining how to use it.

Technical stack

pychron is written entirely with the Python standard library and has no external dependencies. I use subprocess to start the script, threading to run the counter, and the datetime and time modules for timekeeping. The package is built with setuptools through pyproject.toml, supports Python 3.9 and later, and is distributed under the MIT license. Installing it adds a command called pychron.

Use cases

• I use it to see that long data processing and transfer scripts are still running and how long they have been at it.
• I can compare how much an improvement to a script shortened its run time without adding any measurement code.
• Noting how long maintenance and backup scripts take helps me when planning scheduled jobs.