Student Quick Start (Linux, Windows, macOS)

This guide helps you run the LedgerLoom Workbook workflow as a student:

  1. install LedgerLoom from PyPI

  2. create a workbook project with ledgerloom init --profile workbook

  3. run check then build

  4. open the generated CSV artifacts

What you’ll build

LedgerLoom reads CSV inputs from a project folder and generates accounting-cycle artifacts.

After a successful build, you should see these files:

  • entries.csv

  • trial_balance_unadjusted.csv

  • trial_balance_adjusted.csv

  • closing_entries.csv

  • trial_balance_post_close.csv

These files appear under:

  • outputs/<run_id>/artifacts/

Note

ledgerloom check writes a standalone report folder to outputs/check/<period>/ (fast feedback). ledgerloom build --run-id run1 writes a complete run folder to outputs/run1/ and repeats the checks inside outputs/run1/check/ for provenance.

Note

LedgerLoom runs best inside a virtual environment (venv). This keeps your class setup clean and repeatable.

Where to go next

Linux (Ubuntu/Debian)

1) Install Python tools

sudo apt update
sudo apt install -y python3 python3-venv python3-pip

2) Create a workspace + virtual environment

mkdir -p ~/ledgerloom_student
cd ~/ledgerloom_student

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip

3) Install LedgerLoom from PyPI

pip install -U ledgerloom
ledgerloom --help

4) Create a workbook project

ledgerloom init --profile workbook my_books
cd my_books

5) Run the workflow (check → build)

ledgerloom check --project .
ledgerloom build --project . --run-id run1

6) View your outputs

# Standalone check output (fast feedback)
ls -1 outputs/check

# Build output (a named run folder)
ls -1 outputs/run1/artifacts

Common gotchas (Linux)

  • If ledgerloom is “not found”, you likely forgot: source .venv/bin/activate.

  • ledgerloom init requires a folder name at the end (example: my_books).

Windows 11 (PowerShell)

1) Install Python

Install Python 3.10+ from python.org and make sure you check:

  • Add Python to PATH

Verify in PowerShell:

python --version
pip --version

2) Create a workspace + virtual environment

mkdir $HOME\ledgerloom_student
cd $HOME\ledgerloom_student

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip

If activation is blocked, run this once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then activate again:

.\.venv\Scripts\Activate.ps1

3) Install LedgerLoom from PyPI

pip install -U ledgerloom
ledgerloom --help

4) Create a workbook project

ledgerloom init --profile workbook my_books
cd my_books

5) Run the workflow (check → build)

ledgerloom check --project .
ledgerloom build --project . --run-id run1

6) View your outputs

# Standalone check output (fast feedback)
dir outputs\check

# Build output (a named run folder)
dir outputs\run1\artifacts

Common gotchas (Windows)

  • If ledgerloom is not recognized, your venv is not active. Run: .\.venv\Scripts\Activate.ps1

  • If you pasted a multi-line command and PowerShell says something like “command not found”, re-run it as one line.

macOS (Terminal)

2) Create a workspace + virtual environment

mkdir -p ~/ledgerloom_student
cd ~/ledgerloom_student

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip

3) Install LedgerLoom from PyPI

pip install -U ledgerloom
ledgerloom --help

4) Create a workbook project

ledgerloom init --profile workbook my_books
cd my_books

5) Run the workflow (check → build)

ledgerloom check --project .
ledgerloom build --project . --run-id run1

6) View your outputs

# Standalone check output (fast feedback)
ls -1 outputs/check

# Build output (a named run folder)
ls -1 outputs/run1/artifacts

Common gotchas (macOS)

  • Prefer python3 (not python) unless you know python points to Python 3.

  • If ledgerloom is “not found”, you likely forgot: source .venv/bin/activate.