Here’s the guide to building ActivityWatch from source. If you are just looking to try it out, see the getting started guide instead.
Since the main ActivityWatch repository uses git submodules to manage its modules, you first need to clone the repo and then the submodules.
You can do both in one step with:
git clone --recursive https://github.com/ActivityWatch/activitywatch.git
Or, if you’ve already cloned normally, you can clone the submodules using:
git submodule update --init --recursive
Poetry, check with
poetry -V(can be installed like this:
python3 -m pip install poetry)
Node 12 or higher, check with
npm -v(required to build the web UI)
Rust nightly (nightly can be installed using
rustup), check with
cargo -V(for building aw-server-rust)
For Windows users:
gnuwin32, to get the make command on Windows.
(optional) 7 Zip, for packaging the zip.
Commands which should work before building:
If any of these don’t work, make sure you’ve correctly installed them and have them in your PATH variable.
It is highly recommended to use a virtualenv in order to minimize problems and avoid polluting your system with ActivityWatch-specific Python packages. It also makes it easier to uninstall since all you have to do is remove the virtualenv folder.
python3 -m venv venv
Now activate the virtualenv in your current shell session:
# For bash/zsh users: source ./venv/bin/activate # For Windows git bash users: source ./venv/Scripts/activate # For fish users: source ./venv/bin/activate.fish
Now you should be able to start ActivityWatch from the terminal where you’ve activated the virtualenv.
There are two ways to run ActivityWatch:
Use the trayicon manager (Recommended for normal use)
Run from your terminal with:
Start each module separately (Recommended for developing)
Run from your terminal with:
Both methods take the
--testing flag as a command line parameter to run in testing mode. This runs the server on a different port (5666) and uses a separate database file to avoid mixing your important data with your testing data.
Now everything should be running! Check out the web UI at http://localhost:5600/
If anything doesn’t work, let us know!
On Linux, if you want to run from source using a
.desktop file launcher, see issue #176.
First pull the latest version of the repo with
git pull then get the updated submodules with
git submodule update --init --recursive. All that’s needed then is a
If it doesn’t work, you can first try to run
make uninstall and then do a fresh
make build. If that fails as well, remove the virtualenv and start over.
Please report all issues you might have so we can make things easier for future users.
If you made some changes and want to create a proper build with portable executables (like normal ActivityWatch releases) you need to install
pyinstaller (and on Debian-like distros
apt install python3-dev # Or equivalent for your Linux distribution pip3 install --user pyinstaller
Then simply run the following to package it:
When the packaging is done you will have a
./dist folder where you can find:
activitywatchfolder, you can move or copy that folder anywhere you need and set
aw-qtto run from startup.
A zipped version of the folder.
(on Windows) An installer.