Skip to content

Quick Start

This guide walks you through installing Bank Statement Parser and running it on a folder of PDF bank statements for the first time. No technical experience is required.

The whole process takes about five minutes.

Before you begin

You will need:

  • PDF statements downloaded from your bank's online portal
  • A folder to keep them in (e.g. Documents/statements)
  • An internet connection for the one-time installation

Supported statements

Bank Statement Parser currently supports statements from HSBC UK (current accounts, savings accounts, and Rewards Credit Card) and TSB UK (Spend & Save current account). See the home page for the full list.

Step-by-step installation and first run

Step 1 — Install uv

uv is a fast, lightweight tool that manages Python and Python packages for you. You do not need to install Python separately.

  1. Open PowerShell — press Win + S, type PowerShell, and press Enter

  2. Copy and paste the following command, then press Enter:

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

  3. When it finishes, close PowerShell and open a new window — this ensures the new commands are available

Checking it worked

In the new PowerShell window, type uv --version and press Enter. You should see a version number printed, such as uv 0.5.0.

Step 2 — Install Bank Statement Parser

In your PowerShell window, run:

uv tool install uk-bank-statement-parser

This downloads and installs the tool. It only needs to be done once.

Checking it worked

Run bsp --help — you should see a list of available commands.

Step 3 — Put your PDF statements in a folder

Create a folder somewhere easy to find, for example:

C:\Users\YourName\Documents\statements

Copy all of your PDF bank statements into that folder. They can be from different accounts and different months — Bank Statement Parser will sort them out.

Step 4 — Run Bank Statement Parser

In PowerShell, run the following command, replacing the path with the location of your statements folder:

bsp process --pdfs "C:\Users\YourName\Documents\statements"

You will see progress messages as each statement is processed. When it finishes, a new folder called bsp_project will have been created inside your statements folder.

Step 5 — Find your output files

Open C:\Users\YourName\Documents\statements\bsp_project\ in File Explorer.

Your exported files are in the export sub-folder:

bsp_project\
└── export\
    ├── transactions.csv        ← all transactions, one row per line
    ├── transactions.xlsx       ← same data as an Excel workbook
    └── balances.csv            ← opening and closing balances per statement

Open transactions.xlsx in Excel to see all of your transactions in one place.

Running again later

When you receive new statements, just copy them into the same folder and run the same bsp process command again. Existing records will not be duplicated.

Step 1 — Install uv

uv is a fast, lightweight tool that manages Python and Python packages for you. You do not need to install Python separately.

  1. Open Terminal — press Cmd + Space, type Terminal, and press Enter

  2. Copy and paste the following command, then press Enter:

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

  3. When it finishes, run the following to make the new commands available in your current window:

    source $HOME/.local/bin/env

Checking it worked

Type uv --version and press Enter. You should see a version number printed, such as uv 0.5.0.

Step 2 — Install Bank Statement Parser

In Terminal, run:

uv tool install uk-bank-statement-parser

This downloads and installs the tool. It only needs to be done once.

Checking it worked

Run bsp --help — you should see a list of available commands.

Step 3 — Put your PDF statements in a folder

Create a folder somewhere easy to find, for example:

/Users/yourname/Documents/statements

In Finder you can do this by going to Documents and pressing Shift + Cmd + N to create a new folder called statements.

Copy all of your PDF bank statements into that folder. They can be from different accounts and different months — Bank Statement Parser will sort them out.

Step 4 — Run Bank Statement Parser

In Terminal, run the following command, replacing the path with the location of your statements folder:

bsp process --pdfs ~/Documents/statements

You will see progress messages as each statement is processed. When it finishes, a new folder called bsp_project will have been created inside your statements folder.

Step 5 — Find your output files

Open Finder and navigate to:

~/Documents/statements/bsp_project/export/

Your exported files are:

bsp_project/
└── export/
    ├── transactions.csv        ← all transactions, one row per line
    ├── transactions.xlsx       ← same data as an Excel workbook
    └── balances.csv            ← opening and closing balances per statement

Open transactions.xlsx in Numbers or Excel to see all of your transactions in one place.

Running again later

When you receive new statements, just copy them into the same folder and run the same bsp process command again. Existing records will not be duplicated.

Step 1 — Install uv

uv is a fast, lightweight tool that manages Python and Python packages for you. You do not need to install Python separately.

  1. Open a terminal

  2. Copy and paste the following command, then press Enter:

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

  3. When it finishes, run the following to make the new commands available in your current session:

    source $HOME/.local/bin/env

Checking it worked

Type uv --version and press Enter. You should see a version number printed, such as uv 0.5.0.

Step 2 — Install Bank Statement Parser

In your terminal, run:

uv tool install uk-bank-statement-parser

This downloads and installs the tool. It only needs to be done once.

Checking it worked

Run bsp --help — you should see a list of available commands.

Step 3 — Put your PDF statements in a folder

Create a folder somewhere easy to find, for example:

mkdir -p ~/Documents/statements

Copy all of your PDF bank statements into that folder. They can be from different accounts and different months — Bank Statement Parser will sort them out.

Step 4 — Run Bank Statement Parser

Run the following command, replacing the path with the location of your statements folder:

bsp process --pdfs ~/Documents/statements

You will see progress messages as each statement is processed. When it finishes, a new folder called bsp_project will have been created inside your statements folder.

Step 5 — Find your output files

Navigate to the output folder:

cd ~/Documents/statements/bsp_project/export/
ls

Your exported files are:

bsp_project/
└── export/
    ├── transactions.csv        ← all transactions, one row per line
    ├── transactions.xlsx       ← same data as an Excel workbook
    └── balances.csv            ← opening and closing balances per statement

Open transactions.xlsx in LibreOffice Calc or any spreadsheet application to see all of your transactions in one place.

Running again later

When you receive new statements, just copy them into the same folder and run the same bsp process command again. Existing records will not be duplicated.

Something went wrong?

Problem What to try
bsp: command not found Close your terminal/PowerShell window and open a fresh one, then try again
A statement was not processed Check it is from a supported bank and that the PDF is not password-protected
The export folder is empty Check the terminal output for any error messages and raise an issue on GitHub

What's next?