Installing from source¶
Here’s the guide to installing ActivityWatch from source. If you are just looking to try it out, see the getting started guide instead.
This is written for Linux and macOS. For Windows the build process is more complicated and we therefore suggest using the pre-built packages instead on that operating system (but if you really have to, see this guide).
Cloning the submodules¶
Since the ActivityWatch bundlerepo uses submodules, you first need to clone the submodules.
This can either be done at the cloning stage with:
git clone --recursive https://github.com/ActivityWatch/activitywatch.git
Or afterwards (if you’ve already cloned normally) using:
git submodule update --init --recursive
Python 3.6 or later and Poetry, check with
poetry -V(required to build the core components, can be installed like this:
python3 -m pip install poetry)
Node 8 or higher, check with
npm -v(required to build the web UI)
(Optional) Rust nightly and cargo, check with
cargo -V(for building aw-server-rust)
Using a virtualenv¶
If you don’t want to use a virtualenv you could instead set the environment variable
PIP_USER=true when building in the next step.
But make sure that the folder
~/.local/bin (on Linux) or
~/Library/Python/<version>/bin (on macOS) is in your PATH.
It is recommended to use a virtualenv in order to 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
Building and installing¶
Build and install everything into the virtualenv:
If you’re building from source to develop we suggest building/installing using
make build DEV=true which installs all Python packages with pip’s handy
By doing this you wont have to reinstall everything whenever you want to try out a code change.
Now you should be able to start ActivityWatch from the terminal where you’ve activated the virtualenv. Or, if you were using the
PIP_USER trick, from any terminal with a correctly configured PATH.
You have two options:
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.
Updating from source¶
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.
Packaging your changes¶
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
./dist folder where you can find a zipped version and an unzipped
activitywatch folder, you can move or copy that folder anywhere you need and set
aw-qt to run from startup.