Installation

Installation

Contents

• Mac app (no code)
  • The menu-bar icon
  • Sharing a plan
• With the terminal
  • What you need
  • Install pixi
  • Get the code
  • Try the demo
  • Option: a pixi environment inside your plan folder
  • Without pixi
  • Updating

Mac app (no code)

The easiest way on a Mac: no terminal, no code.

1. Download the app from the Releases page: FinancialPlanner-macos-arm64.zip for Apple Silicon (M1 and later) or FinancialPlanner-macos-x86_64.zip for Intel. (Not sure? Apple menu › About This Mac: "Apple M…" means Apple Silicon.)
2. Unzip it and drag Financial Planner into Applications.
3. The first time, right-click the app › Open › Open. macOS asks once because the app isn't signed by Apple yet.
4. The first launch shows "Setting up Financial Planner" for a few minutes (it downloads what it needs; this needs the internet and happens once).
5. It asks how you'd like to start:
   • Start a new plan: an empty plan in FinancialPlan in your home folder.
   • Open a plan someone shared with me: pick the .zip they sent you.
   • Use a plan folder I already have, or choose where to start one.
   • Try the demo: a made-up household to look around.
6. The planner opens in your browser. Next: add your household and bank exports, see the Quick Start.

The menu-bar icon

While the app runs, its icon sits at the top right of your screen. Click it for:

Item	What it does
Open Financial Planner	Opens the planner in your browser.
Plan: …	Shows which plan folder is open.
Change Plan Folder…	Switch to another plan (or turn an empty folder into a new one).
New Plan…	Start a new blank plan in a folder you pick.
Show Plan Folder	Opens the plan in Finder, e.g. to add CSV files.
Open Plan File…	Open a whole plan someone sent you (a .zip).
Save Plan as File…	Save your whole plan as one .zip to send to someone.
Financial Planner 0.x.y	The version you're running.
Check for Updates…	Checks for a newer version; if there is one, installs it and restarts.
Uninstall…	Removes the app and its downloaded files. Your plans are kept.
Quit Financial Planner	Stops it.

• Closing the browser tab doesn't stop it; it keeps running in the menu bar.
• Opening the app again (Applications, Spotlight, the Dock) reuses the running one.
• Quit stops it completely.

Sharing a plan

To give someone (say, your partner) your whole plan, with settings, CSV data and scenarios:

1. You: menu-bar icon › Save Plan as File… (or Settings › Share plan › Save plan as a file). Send the .zip by AirDrop or Messages.
2. They: menu-bar icon › Open Plan File…, or Open a plan someone shared with me on their first launch. If they already have a plan, they choose Keep Both or Replace (their old plan is kept as a backup folder).

The file contains your real transactions: share it privately. To send just a what-if, use Share in the Scenarios bar instead (Scenarios and Sharing).

More detail (updating, uninstalling, troubleshooting): Desktop App.

With the terminal

For Windows and Linux, or if you're comfortable with a terminal on a Mac.

What you need

• macOS, Linux or Windows.
• pixi, which installs Python and every dependency for you. Node is not needed to run the app (only to develop it).
• A web browser.

Install pixi

Follow the instructions at https://pixi.sh. On macOS and Linux it's one line:

curl -fsSL https://pixi.sh/install.sh | bash

Open a new terminal afterwards so the pixi command is found.

Get the code

Only needed for the pixi tasks below or to work on the code. To just use it, pip install financial-planner is enough (see Without pixi).

git clone https://github.com/brookisme/financial_planner.git
cd financial_planner

Try the demo

pixi run demo

The first run downloads Python and the dependencies (a minute or two). Then your browser opens at http://127.0.0.1:8765 with a fictional two-partner, two-child household. Press Ctrl+C in the terminal to stop.

Next: Quick Start to make your own plan.

Option: a pixi environment inside your plan folder

You can always run commands from the financial_planner folder and pass your plan's path (pixi run financial_plan start ~/MyFinancialPlan). If you'd rather run from inside the plan folder, give it its own pixi.toml:

[workspace]
name = "my-financial-plan"
channels = ["conda-forge"]
platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]

[dependencies]
python = ">=3.11,<3.14"

[pypi-dependencies]
financial-planner = { version = ">=0.1", extras = ["desktop"] }     # from PyPI
# or a local checkout you're developing:
# financial-planner = { path = "/path/to/financial_planner", editable = true }

cd ~/MyFinancialPlan
pixi run financial_plan start

Without pixi

Any Python 3.11+ works; the package is on PyPI (no git needed):

pip install financial-planner                 # or "financial-planner[desktop]" for the Mac menu-bar app
financial_plan init ~/MyFinancialPlan
financial_plan start ~/MyFinancialPlan

Update later with pip install -U financial-planner.

Updating

cd financial_planner
git pull

Your plan folder lives elsewhere and isn't touched. Reload the app (or restart financial_plan start) to pick up the new version.