Skip to content

Installation Guide

This guide will walk you through installing, verifying, and uninstalling Spendwise Tracker.

Requirements

Before installing Spendwise Tracker, ensure your system meets the following requirements:

  • Python: Version 3.11 or higher
  • Operating System: macOS, Linux, or Windows
  • uv: Package installer (installation instructions below)

Installing uv

Spendwise Tracker is distributed as a Python package and is best installed using uv, a fast Python package installer and resolver.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, you may need to restart your terminal or add uv to your PATH.

Installing Spendwise Tracker

Once you have uv installed, you can install Spendwise Tracker using the uv tool install command:

uv tool install spendwise-tracker

This command will:

  1. Download the latest version of Spendwise Tracker from PyPI
  2. Install it in an isolated environment
  3. Make the expense-tracker command available in your terminal

Installing a Specific Version

To install a specific version, use:

uv tool install spendwise-tracker==0.1.0

Check the Releases page for available versions.

Verifying the Installation

After installation, verify that Spendwise Tracker is working correctly:

1. Launch the Application

Start the application to ensure the GUI launches properly:

expense-tracker

The Spendwise Tracker GUI window should open. If the application starts successfully, the installation is complete!

2. Verify Database Location

On first launch, Spendwise Tracker will create its database files in a platform-specific location:

~/Library/Application Support/spendwise-tracker/

~/.local/share/spendwise-tracker/

%LOCALAPPDATA%\spendwise-tracker\

You can verify these directories exist after launching the application once.

Troubleshooting

Command Not Found

If you get a "command not found" error after installation:

  1. Check if uv's bin directory is in your PATH:

    echo $PATH

    echo %PATH%

  2. Add uv's bin directory to your PATH:

    Add to ~/.bashrc or ~/.zshrc:

    export PATH="$HOME/.local/bin:$PATH"

    uv typically adds itself to PATH automatically during installation.

  3. Restart your terminal and try again

Python Version Issues

If you encounter Python version errors:

# Check your Python version
python --version

Or:

python3 --version

Ensure Python 3.11 or higher is installed. If not, install or update Python before proceeding.

Permission Errors

On macOS/Linux, if you encounter permission errors, ensure you're not using sudo. The uv tool install command should work without elevated privileges.

Updating Spendwise Tracker

To update to the latest version:

uv tool upgrade spendwise-tracker

To update to a specific version:

uv tool install spendwise-tracker==0.2.0 --force

Uninstalling Spendwise Tracker

Uninstall the Application

To remove Spendwise Tracker from your system:

uv tool uninstall spendwise-tracker

This will remove the application but will not delete your data.

Remove User Data

If you also want to delete your transaction data and merchant categories, manually remove the data directory:

rm -rf ~/Library/Application\ Support/spendwise-tracker/

rm -rf ~/.local/share/spendwise-tracker/

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\spendwise-tracker"

Data Loss Warning

Deleting the data directory will permanently remove all your transactions, merchant categories, and settings. This action cannot be undone. Make sure to back up your data if needed before proceeding.

Getting Help

If you encounter issues not covered in this guide:

  1. Check the GitHub Issues page
  2. Open a new issue with details about your problem