Calculates capital gains tax using the Austrian moving average cost basis method (Gleitender Durchschnittspreis) for stocks acquired through RSU vesting and ESPP purchases.
⚠️ DISCLAIMER: This software is provided "as is", without warranty of any kind. Use at your own risk. The calculations are based on my understanding of Austrian tax law and may contain errors. This tool is not a substitute for professional tax advice. Always verify the results with a qualified tax advisor (Steuerberater) before filing your tax return. The author(s) assume no liability for any financial losses, penalties, or other damages arising from the use of this software.
If you are not a developer, you can simply use the provided script:
- Download the entire project as a ZIP from GitHub (click "Code" → "Download ZIP") and extract it.
- Double-click the
run_tax_engine.commandfile inside the extracted folder. - It will automatically set up Python, install dependencies, and open a menu.
- Follow the menu options to Login, Download Data, and Calculate Tax.
Note: The first time you run it, you might need to right-click and select "Open" if macOS warns about an unidentified developer, or allow it in System Settings.
If you are not a developer, you can simply use the provided script:
- Download the entire project as a ZIP from GitHub (click "Code" → "Download ZIP") and extract it.
- Double-click the
run_tax_engine.batfile inside the extracted folder. - It will automatically set up Python, install dependencies, and open a menu.
- Follow the menu options to Login, Download Data, and Calculate Tax.
If you are not a developer, you can use the same script as Mac users:
- Download the entire project as a ZIP from GitHub (click "Code" → "Download ZIP") and extract it.
- Open a terminal in the extracted folder and run:
chmod +x run_tax_engine.command ./run_tax_engine.command
- It will automatically set up Python, install dependencies, and open a menu.
- Follow the menu options to Login, Download Data, and Calculate Tax.
In Visual Studio Code, open this workspace using the Dev Containers extension to run it inside the provided development container.
The container includes a lightweight desktop (fluxbox) and a Chromium browser installed via Playwright (will be installed after creating the container).
Security note: The container runs with elevated privileges so Playwright's Chromium can run correctly. This isolates the container's browser from your host browser but is not a hardened sandbox - do not rely on it as an unescapable security boundary for untrusted code.
Access the desktop:
- Open in a browser at http://localhost:6080
- Or connect with a VNC client on port 5901 (port may vary; check the VS Code "Ports" tab)
Start the download assistant (it opens the browser inside the container):
uv run tax-downloadUse the assistant to log in to E-Trade and download the required files (ESPP history, Orders, RSU confirmations).
brew install uv
uv sync --all-extras
uv run pre-commit installTo see the tax engine in action with sample data:
uv run demo.pyTo automate downloading transaction history from E-Trade:
-
Install Playwright browsers (first time only):
uv run playwright install chromium
-
Run the download assistant:
uv run tax-download
This will guide you through login and automatically download all required files (ESPP history, Orders, and RSU confirmations).
Alternatively, you can run individual tasks:
uv run tax-login uv run tax-download-espp uv run tax-download-orders uv run tax-download-rsu uv run tax-download-options
The downloads land in
input/:Path Contents Required input/espp/BenefitHistory.xlsxESPP purchases only if you have ESPP input/orders/orders.xlsxSell orders only if you sold shares input/rsu/*.pdfRSU release confirmations only if you have RSUs input/options/*.pdfOptions exercise confirmations only if you have options input/etrade_session.jsonYour logged-in E-Trade session (cookies) created by tax-loginAny combination works; the engine simply skips sources that are not present.
Once your data is in the input/ directory:
uv run main.py # all years
uv run main.py --year 2025 # one tax year
uv run main.py --input-dir ~/data # data somewhere elseIt will print the ledger and yearly summary and write tax_report_*.pdf. The command exits with a non-zero status if no transactions were found, the requested year has no data, or the PDF could not be written.
To file one year, pass --year:
uv run main.py --year 2025This limits the calculation and the report to that year and builds a submission
bundle in output/Steuerakt_2025/:
output/Steuerakt_2025/
├── Steuerakt_2025_komplett.pdf ← the single file to submit
├── 00_Steuerbericht_2025.pdf ← the tax report on its own
├── Belegverzeichnis_2025.csv ← document index as CSV
├── README.txt ← what is in the bundle and why
├── belege/ ← every source document, named by Beleg-Nr.
│ ├── B-001_RSU_Confirmation_<date>_<id>.pdf
│ ├── …
│ ├── B-034_BenefitHistory_extract.pdf
│ └── B-035_orders_extract.pdf
└── source_data/ ← the untouched original workbooks
Steuerakt_2025_komplett.pdf contains a cover page, the tax report, and then every
document behind a cover sheet carrying its Beleg-Nr. Each row of the transaction
ledger in the report cites that number, so the Finanzamt can follow any figure back
to its document. A ZIP of the folder is written next to it.
Useful flags:
| Flag | Effect |
|---|---|
--year 2025 |
Limit the calculation and report to tax year 2025 |
--no-bundle |
Just print the report and write a single PDF |
--output-dir DIR |
Write the bundle somewhere other than ./output |
--no-zip |
Skip the ZIP archive |
Austria requires the moving average cost basis, so the gain on a 2025 sale is the sale price minus the average cost of the whole holding — which earlier vests and purchases built up. The bundle therefore separates:
- Primary documents: the transactions of the filed year.
- Supporting documents: the earlier acquisitions that establish the average cost carried into 1 January of that year. They are not taxed in the report; they are there to substantiate the opening figure. They reach back only to the last date the depot was empty, because the average cost resets at that point.
Appendix A of the report reproduces those earlier transactions so the opening average cost can be recomputed line by line.
The tax report output includes the values you need for your Austrian tax return (Formulars E1 / E1kv):
| Kennzahl | Description | Value to enter |
|---|---|---|
| 994 | Realized gains from capital assets (Einkünfte aus Kapitalvermögen) | Total gains for the year |
| 892 | Realized losses from capital assets (Verluste aus Kapitalvermögen) | Total losses for the year (as a negative number) |
These Kennzahlen are shown in both the console output and the generated PDF report.
tax-login opens a real, visible Chromium window for you to sign in (including MFA); the tool never sees your password. Be aware of two things:
- The browser is launched with settings that make it present as an ordinary desktop Chrome (for example hiding the
navigator.webdriverflag), because E-Trade otherwise refuses to load the login page in an automated browser. Automated access may be restricted by E-Trade's terms of use; you are responsible for deciding whether to use it. - The session is stored in
input/etrade_session.json. That file grants access to your brokerage account for as long as the session is valid. It is excluded from git by.gitignore; do not copy it anywhere else and delete it when you are done.
For a detailed explanation of the tax calculation methodology, including the moving average cost basis formula, currency conversion, and practical examples, see the Tax Calculation Method documentation.