{"id":47394397,"url":"https://github.com/Evernight/beancount-plugin-tax-uk","last_synced_at":"2026-04-03T07:01:17.758Z","repository":{"id":285253584,"uuid":"943361737","full_name":"Evernight/beancount-plugin-tax-uk","owner":"Evernight","description":"Beancount plugin for generating informational UK tax report (calculate capital gains tax)","archived":false,"fork":false,"pushed_at":"2026-02-15T19:44:45.000Z","size":808,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T01:38:06.882Z","etag":null,"topics":["beancount","capital-gains","capital-gains-calculator","cgt","uk-tax-calculator"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Evernight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-05T15:30:22.000Z","updated_at":"2026-02-15T19:44:49.000Z","dependencies_parsed_at":"2025-03-30T16:38:47.116Z","dependency_job_id":null,"html_url":"https://github.com/Evernight/beancount-plugin-tax-uk","commit_stats":null,"previous_names":["evernight/beancount-plugin-tax-uk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Evernight/beancount-plugin-tax-uk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evernight%2Fbeancount-plugin-tax-uk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evernight%2Fbeancount-plugin-tax-uk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evernight%2Fbeancount-plugin-tax-uk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evernight%2Fbeancount-plugin-tax-uk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Evernight","download_url":"https://codeload.github.com/Evernight/beancount-plugin-tax-uk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evernight%2Fbeancount-plugin-tax-uk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31341836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T06:57:30.245Z","status":"ssl_error","status_checked_at":"2026-04-03T06:57:29.849Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beancount","capital-gains","capital-gains-calculator","cgt","uk-tax-calculator"],"created_at":"2026-03-20T04:00:23.334Z","updated_at":"2026-04-03T07:01:17.750Z","avatar_url":"https://github.com/Evernight.png","language":"Python","funding_links":[],"categories":["Plugins"],"sub_categories":["Fava"],"readme":"# Beancount Plugin Tax UK\n\nCapital gains and others tax calculator for UK for investments described in [Beancount](https://github.com/beancount/beancount/) format.\nImplemented as a plugin for Beancount / Fava that generates United Kingdom tax reports for capital gains, dividends and other investment income, exportable as Excel / xls spreadsheet.\n\n## DISCLAIMER\n\n**This software is provided \"as is\" without warranty of any kind. The author is neither an accountant nor a finance specialist. Please verify all calculations and consult with a qualified tax professional. This tool is meant to assist with tax calculations but should not be solely relied upon for tax filing purposes.**\n\n## Functionality\n\nThis plugin helps calculate UK capital gains tax and generate reports for:\n\n* ✅ Capital gains calculations including handling of Section 104 holding, Bed \u0026 Breakfast, and Same Day rules\n* ✅ Supporting generic case for various asset types (stocks, crypto, etc.),  platforms, and common event types\n* ✅ Dividend income and other investment income\n* ✅ Multiple currencies with tax report generated using HMRC or Beancount exchange rates\n* ✅ Stock splits\n* ✅ Excess reportable income (for accumulation funds)\n* ⚠️ Equalisation payments\n  \u003e See [tests](https://github.com/Evernight/beancount-plugin-tax-uk/blob/main/tests/README.md) and linked [discussion](https://github.com/mattjgalloway/cgtcalc/issues/15)) for details on possible implementations\n* ❌ Showing allowances and actual tax liability (only calculates gains and losses), filing tax return\n  \u003e Consult with approrpiate year's official resources and maybe even use licensed software for actually sending out the tax return (after checking your data and possibly consulting with specialist)\n* ❌ Any old tax rules, e.g transactions before 6th April 2008\n  \u003e Won't be supported\n\n## Available as\n* A command-line tool to generate Excel reports\n* A Fava plugin for interactive viewing\n\n### Screenshots\n\u003cimg src=\"screenshots/fava_report.png\" width=\"60%\" hspace=\"10\" vspace=\"10\"/\u003e\n\u003cimg src=\"screenshots/excel_report.png\" width=\"60%\" hspace=\"10\" vspace=\"10\"/\u003e\n\n## Configuration\n\n### Setup\nInstall the plugin:\n```bash\npip install git+https://github.com/Evernight/beancount-plugin-tax-uk\n```\nand enable it in the ledger:\n\n```beancount\nplugin \"beancount_plugin_tax_uk.fava_extension\"\n```\n\nYou'll also need to add some metadata to your transactions to make it work.\n\n### Transaction types\n\nTag your transactions with the following to mark them for tax processing:\n\n* `#buy` - Asset purchases\n* `#sell` - Asset sales\n* `#vest` - Share vesting events\n* `#stock_split` - Stock splits\n* `#dividend` - Dividend income\n* `#interest` - Interest income\n* `#ERI` - Excess reportable income (for accumulation funds)\n* `#taxed_income` - Any other type of taxed income (totals will be aggregated by year for the report)\n\nOnly transactions with one of these tags will be considered by the plugin. If you want to tag groups of transactions (e.g. all transactions for a specific account) without manually editing the ledger, I'd recommend using [filter_map](https://github.com/Evernight/beancount-lazy-plugins?tab=readme-ov-file#filter_map) plugin\n\nExample transactions:\n\n```beancount\n2023-04-06 * \"Buy shares\" #buy\n  Assets:IBKR:Stocks    10 VWRL {50.00 GBP}\n  Assets:IBKR:Cash    -500.00 GBP\n  Expenses:Commissions          2.00 GBP\n\n2023-05-01 * \"Sell shares\" #sell\n  Assets:IBKR:Stocks    -5 VWRL {} @ 52.00 GBP\n  Assets:IBKR:Cash    260.00 GBP\n  Expenses:Commissions          2.00 GBP\n```\n\nMore examples are available as ```beancount``` files in the [test data folder](tests/data).\nYou can start Fava with multiple ledgers available via a dropdown selector with:\n```\nmake show-tests\n```\n\n### Optional plugin configuration\n\nPlugin is designed to work out of the box without additional configuration when you add the corresponding tags to your transactions. However you may want to adjust its behaviour to adapt it to your Beancount ledger structure and naming conventions.\n\n```beancount\n; Map account name to a descriptive shortname of a platform and default asset type\n; 2000-01-01 custom \"uk-tax-platform-mapping\" \u003cpattern\u003e \u003cplatform\u003e [\u003casset_type\u003e]\n2000-01-01 custom \"uk-tax-platform-mapping\" \"Assets:SomeBroker:.*\" \"Broker123\" \"Stocks\"\n2000-01-01 custom \"uk-tax-platform-mapping\" \"Assets:SomeCryptoPlatform:.*\" \"SomeCryptoPlatform\" \"Crypto\"\n\n; Map Beancount commodities to name and asset class used in the report\n; 2000-01-01 custom \"uk-tax-asset-mapping\" \u003csymbol\u003e \u003cmapped name\u003e [\u003casset_type\u003e]\n2000-01-01 custom \"uk-tax-asset-mapping\" \"VWRL\" \"VG FTSE All-World\" \"Stocks\"\n2000-01-01 custom \"uk-tax-asset-mapping\" \"ETH\" \"Ethereum\" \"Crypto\"\n\n; \u003casset_type\u003e can be \"Stocks\" or \"Crypto\"\n\n; Additional configuration for special account treatment\n2000-01-01 custom \"uk-tax-config\" \"commission-account\" \"^Expenses:.*:Commissions\"\n2000-01-01 custom \"uk-tax-config\" \"income-account\" \"^Income:.*\"\n```\n\n### Using command line \n\n```bash\npython3 -m beancount_plugin_tax_uk.calculate_tax --help\n```\n\nIf you have currencies in the tax return that are not GBP, the Beancount ```price``` directives will be used by default. If you want to use official HMRC conversion rates, you'll need to download them in special format as in https://github.com/matchilling/hmrc-exchange-rates.\n\n### Plugin configuration\n\nFor Fava integration, add the following line to your Beancount file:\n\n```beancount\nplugin \"beancount_plugin_tax_uk.fava_extension\"\n```\n\nThe ```UK Taxes``` link should appear in the Fava interface.\n\n### Using with Lazy Beancount\n\n[Lazy Beancount](https://github.com/Evernight/lazy-beancount/) contains set of plugins that make keeping track of your investments and other financial operations easier.\nThis plugin is included in the ```extra``` build on Docker Hub:\n```\ndocker pull vandereer/lazy-beancount:extra\n```\n\n## Verification and tests\n\nObviously, correctness of the results is very much desired. Relevant references to HMRC resources inserted in code where appropriate. Some end-to-end tests are provided taken from various sources.\nI found https://github.com/mattjgalloway/cgtcalc to have the most structured test suite, kudos to the author of the tool. Of course, before starting to treat these as a source of truth, refer to the disclaimer and discussions in that repository as well.\n\nNevertheless, this repository contains a simple parser from ```cgtcalc```'s format into Beancount file, and the test case inputs converted accordingly. To compare outputs with ```cgtcalc```'s expected output you'd have to compare ```xlsx``` reports with ```txt``` files manually, or alternatively run ```show_tests_in_fava.sh``` (```make show-tests```) and compare outputs with reports from ```cgtcalc```.\nNote that at this point while some cases are treated identically, there are a few observed differences (that may be fixed in future).\n\n```bash\nmake test\n```\n\nNote differences in the test results mentioned [on the tests README page](tests/README.md).\n\nIf you have more test cases to contribute, particularly if the results are verified/confirmed in some way and/or contain some cases not covered by the current tests, please share.\n\n## Other countries\n\nThis plugin is designed to work with UK tax rules (even for that case, see the disclaimer above). However, few other countries have similar rules, e.g. in handling capital gains using average cost basis. If you're interested in adapting the plugin, feel free to open an issue, submit a pull request or even fork repository in case implementing these is not generalisable or requires too many changes.\n\n## See also\n* 🪙 [Evernight/lazy-beancount](https://github.com/Evernight/lazy-beancount) - Beancount pre-packaged in Docker with plugins, in case you're just starting with Beancount or want to upgrade your experience. Includes this plugin in ```extra``` package.\n\nAnd other open source capital gains tax calculators for the UK:\n* 🧮 [mattjgalloway/cgtcalc](https://github.com/mattjgalloway/cgtcalc) - tax reporting for UK from custom format, written in Swift\n* 🧮 [KapJI/capital-gains-calculator](https://github.com/KapJI/capital-gains-calculator) - tax reporting for UK, with few selected platforms supported\n* 🧮 [BittyTax/BittyTax](https://github.com/BittyTax/BittyTax) - tax reporting for UK, only for crypto\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvernight%2Fbeancount-plugin-tax-uk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEvernight%2Fbeancount-plugin-tax-uk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvernight%2Fbeancount-plugin-tax-uk/lists"}