Overview

This document describes the complete workflow for:

  • Exporting a GnuCash SQLite (.gnucash) file
  • Converting it to Beancount
  • Viewing it in Fava
  • Using uv-managed Python
  • Keeping virtual environments outside OneDrive

This setup assumes:

  • Windows 11
  • uv-managed Python (installed in C:\Dev\uv-python)
  • Virtual environments in C:\Dev\venvs
  • Project folder inside OneDrive

Project Location

Project folder:

C:\Users\Preston\OneDrive\Projects\gnucash-beancount

Recommended structure:

gnucash-beancount\
  tools\
  data\
  out\
  README.md

Create it:

mkdir "C:\Users\Preston\OneDrive\Projects\gnucash-beancount"
cd "C:\Users\Preston\OneDrive\Projects\gnucash-beancount"
mkdir tools, data, out | Out-Null

Initialize uv Project

From project root:

uv init

Bind project to an external venv (outside OneDrive):

$env:UV_PROJECT_ENVIRONMENT = "C:\Dev\venvs\gnucash-beancount"
uv venv --python 3.13

Install Dependencies

Install required packages:

uv add piecash sqlalchemy beancount fava
uv sync

Verify:

uv run python -c "import piecash, sqlalchemy, beancount; print('OK')"
uv run fava --version

Add Export Script

Place your exporter script in:

tools\export_gnucash_to_bean.py

Add GnuCash File

Place your .gnucash SQLite file in:

data\mybook.gnucash

Example:

copy "D:\path\to\yourbook.gnucash" ".\data\mybook.gnucash"

Export to Beancount

From project root:

uv run python .\tools\export_gnucash_to_bean.py .\data\mybook.gnucash > .\out\main.bean

Confirm output exists:

Get-Item .\out\main.bean

Optional validation:

uv run python -c "from beancount.loader import load_file; e,err,_=load_file(r'out\main.bean'); print('errors:', len(err))"

Launch Fava

uv run fava .\out\main.bean

Open the URL shown (typically http://127.0.0.1:5000).

Daily Workflow

Open project:

cd "C:\Users\Preston\OneDrive\Projects\gnucash-beancount"

Set venv:

$env:UV_PROJECT_ENVIRONMENT = "C:\Dev\venvs\gnucash-beancount"

Sync dependencies (if needed):

uv sync

Export:

uv run python .\tools\export_gnucash_to_bean.py .\data\mybook.gnucash > .\out\main.bean

Launch UI:

uv run fava .\out\main.bean

OneDrive Notes

  • Project folder is safe inside OneDrive.
  • Virtual environments stay outside OneDrive (C:\Dev\venvs).
  • uv-managed Python stays outside OneDrive (C:\Dev\uv-python).
  • Beancount output (.bean) is text and sync-friendly.
  • Large .gnucash files may sync slowly; optionally store them outside OneDrive and reference by full path.

Environment Locations Summary

Component Location
uv Python installs C:\Dev\uv-python
uv cache C:\Dev\uv-cache
Project venv C:\Dev\venvs\gnucash-beancount
Project code OneDrive
Beancount output OneDrive

End State

You now have:

  • Deterministic uv-managed Python
  • Clean external virtual environment
  • GnuCash → Beancount conversion workflow
  • Fava UI for inspection
  • OneDrive-safe layout