Track, analyze and visualize your personal finances using CSV data, with automated email reports.
This project reads your transaction data from a CSV file, performs detailed analysis, generates charts and sends a summary report via email. It allows you to monitor income, expenses, savings, budget adherence and recurring vs discretionary spending.
- Reads transaction data from a CSV file
- Calculates total income, total expenses, net savings and savings rate
- Identifies top 5 spending categories
- Tracks month-over-month changes in income, expenses and net savings
- Compares budget vs actual spending (if budget data available)
- Distinguishes recurring and discretionary expenses
- Generates charts: Income vs Expenses, Category Spending, Net Cash Flow, Budget vs Actual, Recurring vs Discretionary, Cumulative Net Worth
- Sends an HTML email report with charts and highlights
- Clone the repository
git clone https://github.com/yourusername/finance-tracker.git
cd finance-tracker
- Install dependencies
pip install -r requirements.txt
- Configure environment variables
Create a .env file (do not upload it to GitHub) with your email credentials:
EMAIL_SENDER=youremail@example.com
EMAIL_PASSWORD=yourpassword
- Prepare your CSV file
Ensure your CSV has the following columns:
date→ Transaction date (DD/MM/YYYY)amount→ Transaction amount (positive for income, negative for expenses)category→ Category of transaction (e.g., Food, Rent, Income)recurring→ TRUE/FALSE for recurring expensesbudget→ (Optional) Budget amount per category
Example file: sample_bank_data.csv
Run the main script:
python main.py
The script will:
- Generate charts in the
output/folder - Send an HTML email with highlights, charts and detailed financial report
- Show metrics like total income, total expenses, net savings, savings rate and month-over-month changes
- Charts: Visualizations for income vs expenses, top spending categories, net cash flow, budget vs actual, recurring vs discretionary, cumulative net worth
- Highlights: Key insights like overspending, savings rate and discretionary spending alerts
- Scorecards: Metrics and comparisons embedded in the email for quick review
- pandas → For data manipulation
- matplotlib → For plotting charts
- numpy → Optional numerical calculations
- smtplib, email.mime → For sending email
- python-dotenv → For reading environment variables
Python version recommended: 3.10+
- Email is sent via SMTP (Gmail in the current setup). Make sure your email allows "less secure apps" or use an app password.
- Charts are saved locally and embedded inline in the email.
- Budget comparison is optional; the app works even if the CSV lacks a budget column.
- This tool is for personal finance tracking and educational purposes.
- Always ensure your email credentials are kept private.
This project is licensed under the MIT License.