pydoro 🍅

Terminal Pomodoro Timer Pydoro is a terminal-based Pomodoro timer designed to help you improve focus and productivity using the Pomodoro Technique. This technique breaks down work into intervals, traditionally 25 minutes of focused work followed by a short break, with longer breaks after completing a set number of intervals. Pydoro provides a simple, distraction-free interface for using this method directly in your terminal.

Installation 🎉

Follow the instructions below to install Pydoro and get started with this Pomodoro timer.

Install via pip (Python Package Index):

The simplest way to install Pydoro is through pip. This method is compatible with Python 3.6+.

$ pip install pydoro
$ pydoro

After installation, you can run Pydoro directly from the terminal using the pydoro command.

Install via snap (Linux):

If you're using a Linux system, you can also install Pydoro via Snap, which is a universal package manager:

$ sudo snap install pydoro
$ pydoro

• Note for Pop!_OS users: If you're using Pop!_OS, use the --no-sound option when running Pydoro to avoid sound playback, as this may conflict with system settings.

Install with Audio Dependencies (macOS/Linux):

If you want to enable audio features (such as sound notifications) on macOS or Linux, you'll need to install the required dependencies. You can do so by running the following command:

$ pip install "pydoro[audio]"

• For macOS: It will install pyobjc-core.
• For Linux: It will install PyGObject for audio functionality.
• If you encounter issues with PyGObject, Pygame will be used if it is installed.

Use pip3 (For Certain Systems):

If your system uses pip3 instead of pip, you can use the following command to install Pydoro:

$ pip3 install pydoro

Install via pipx (Recommended for Isolated Environments):

If you prefer to run Pydoro in an isolated environment using pipx, you can install it with the following command:

$ pipx install pydoro

You can also inject additional dependencies, like Pygame for sound support, into the pipx environment:

$ pipx inject pydoro pygame

Usage 📖

Once installed, you can start using Pydoro directly from your terminal with the following command:

$ pydoro

This will launch the Pomodoro timer interface in your terminal.

Available Options:

• --no-sound: Disables the sound notifications, allowing for a quieter experience.
• --no-clock: Hides the Pomodoro clock display during the timer countdown.
• --focus: Hides the clock and disables sound to help you focus fully during the Pomodoro session.

For a more in-depth look at the features, refer to the [Pydoro Wiki](https://github.com/JaDogg/pydoro/wiki).

A demonstration of Pydoro in action:

Credits 🙇‍♂️

Pydoro has benefited from the contributions of various individuals and libraries. Here's a list of the notable contributors and resources:

• Pomodoro Technique: The Pomodoro Technique, developed by Francesco Cirillo, is the core concept behind Pydoro. It involves working in short, focused intervals followed by breaks to enhance productivity. - Learn more about it on [Wikipedia](https://en.wikipedia.org/wiki/Pomodoro_Technique).
• playsound.py: Pydoro uses this simple Python module for playing sound notifications during Pomodoro sessions. - Repository: [playsound.py - Taylor Marks](https://github.com/TaylorSMarks/playsound).
• prompt-toolkit: This library is used for building interactive command-line applications, providing the UI for Pydoro in the terminal. - Repository: [prompt-toolkit](https://github.com/prompt-toolkit/prompt_toolkit).
• b15.wav: A sound file used for alarm notifications in Pydoro, created by Dana Robinson and released under CC0. - Sound file: [b15.wav - Dana Robinson](https://freesound.org/s/377639/).

Contributors 🙏

• Gabriel Cruz - gmelodie
• Zach Nelson - requiem
• Kajpio - kajpio
• Manuel Gutierrez - xr09
• kiba - islander
• Beatriz Uezu - beatrizuezu
• Zlatan - zlatsic
• Karolis Mažukna - nikamura
• AKeerio - akeerio
• Rohn Chatterjee - liupold
• James Tigert - kz6fittycent
• Kana - kana

Why? 🤔

Pydoro was created with the following objectives in mind:

• Simplification: Provide a lightweight, terminal-based Pomodoro timer that doesn't require external applications or online tools.
• Privacy: Operate entirely offline, ensuring that no user data is collected or tracked.
• Productivity: Offer a distraction-free way to manage work intervals, helping users stay productive throughout their day.
• Customization: Written in Python to be easily customizable and extendable according to personal or organizational needs.

Copyright ⚖

Pydoro is released under the MIT License. Copyright (c) 2021 - 2025 Bhathiya Perera.

For licensing details, please refer to the LICENSE file.