LuaBill — User guide

LuaBill creates business documents locally with LuaLaTeX: invoices, quotations, purchase orders and other correspondence. Use the form to edit your data; editing a .bill file is unnecessary. This guide follows the language of the interface. The language printed in your document is a separate choice.

Contents: First document · Open and save · Document and VAT · Seller and customer · Items and totals · Remarks · Received advances · Output, QR and images · Electronic invoices · Components · Settings and reset · Problems · Keyboard · Licenses

You can leave this guide open while editing your document. Press Ctrl+F (Cmd+F on macOS) to search, use the previous/next controls to move between matches, and use the contents button to return to the navigation.

1. Create your first document

1. Choose File → New, or File → Example to explore a completed example. Example company and tax details are fictional: replace them before use.
2. On Document, select the document type, document language, number, dates, currency and tax scenario. Check the draft watermark.
3. Complete Seller and Customer, including structured postal addresses and country codes. Add your bank and tax details.
4. On Items, add the goods or services. Add any Remarks and actual Received advances.
5. On Files and output, choose a format and an output folder. Initially, ordinary PDF is the simplest format to review.
6. Choose Document → Check totals (F7). Correct the reported data errors, then choose Create PDF / XML (F9). A new document first needs a project filename.
7. Inspect the opened PDF and the result panel. For electronic invoices, also confirm that external validation passed before sending the result.

2. Projects, opening and saving

Save writes the current project. Save as… creates a project at a different path. Drafts may be saved before mandatory invoice fields are complete. File → Export .bill… explicitly exports input for the older handler. A seller profile is a separate JSON file, saved through Settings → Save seller profile.

Opening a project or example does not create unsaved changes. An asterisk in the title means that document data has been edited. Generation saves a new or edited project first. An already opened, unchanged .luabill is generated without asking for another filename or rewriting the project. Settings saved on exit do not replace Save for your document.

Open and first-save dialogs remember the last project folder. Save as proposes the current project's folder. With a registered file association, double-clicking a .luabill opens its data in LuaBill. The Windows installer offers that association; source installations can use Settings → Associate .luabill files with LuaBill…. After moving a source installation, register its new location again.

3. Document, language, currency and VAT

The current currency code remains visible in the toolbar and window title on every tab. It updates when you change the currency or open a document.

The Document tab selects quotation, invoice, delivery note, order confirmation, proforma invoice, purchase order, credit note, cancellation invoice, quotation request or letter. Invoice stage distinguishes full, advance, partial and final invoices. Enter your own document number: LuaBill does not assign or check a business-wide sequence. Enter the actual issue date and delivery/service date. Payment days and offer validity are separate values. Credit and cancellation documents reference the original invoice number and, where available, its date.

Document language chooses EN, DE, FR, IT or RU for printed labels and standard text. Settings → Interface language changes menus, help and buttons independently. Neither option translates your product descriptions or custom prose. Changing an existing document's language changes its data; changing only the interface does not.

Use a three-letter currency code such as EUR, USD, JPY, RUB or CNY, independently of the customer's country. RUB and CNY are also available in the currency list. Enter amounts in that currency; no exchange-rate conversion takes place. Electronic monetary totals support at most two decimal places. Currencies normally using three or four minor digits need an explicit two-decimal export configuration in the underlying input; this is not a separate GUI field.

Choose the tax scenario that matches the actual transaction: domestic Germany, goods to an EU business, goods outside the EU, ordinary EU B2B services, or ordinary non-EU B2B services. For goods, enter the Actual delivery country. A foreign customer alone does not establish a VAT exemption.

The document VAT rate is the default for items. A blank VAT category selects automatic handling. Use an explicit category and exemption reason only when appropriate. Small-business exemption (§19 UStG) is a domestic shortcut. Selecting a foreign scenario clears item VAT overrides and sets the document rate to zero; selecting the small-business option also clears overrides. Review the items after changing these choices.

LuaBill generates VAT explanations and statutory references from the selected scenario and calculated tax groups. The Clickable statutory links option controls links, not the underlying explanations or citations. Special transactions, B2C/OSS and evidence supporting an exemption require separate assessment; selecting a scenario does not establish tax eligibility.

4. Seller and customer

The optional Customer number is your identifier for this customer. Enter it as text, for example 000123, to retain leading zeros, or leave it empty. LuaBill prints it in the PDF and exports it as the buyer identifier in electronic XML (customer.buyer_id). It is separate from the invoice number, purchase-order reference and buyer reference/Leitweg-ID.

Enter the company/full name, street and number, optional second address line, postal code, city and two-letter ISO country code. The current version supports sellers in Germany only: use DE for the seller. Customers may be in Germany, another EU country or outside the EU, for example DE, FR or US. Use ordinary text. Seller and customer addresses feed both the PDF and XML.

For every electronic export (XML, XRechnung and ZUGFeRD), the current implementation requires a valid seller IBAN. This is a LuaBill validation requirement, including when the document uses a currency other than EUR.

For the seller, enter the contact/signatory, email, telephone, website, tax number and/or VAT ID, bank, IBAN and BIC. Tax ID means the seller's tax number (Steuernummer); it is distinct from the VAT ID (USt-IdNr.) and the company registration number. Fill in the legal form, registered office, register court, registration number, all managing directors (one per line) and supervisory-board chair where applicable. A contact/signatory does not replace the full director list.

For the customer, enter the purchase-order reference, contact and any separate delivery recipient/address. The buyer reference/Leitweg-ID is on the Document tab. Use the exact routing reference supplied by the recipient; an arbitrary order number is not automatically a valid Leitweg-ID.

Customer contact details have separate inputs for Contact name, Role, Email, Telephone, Mobile, Fax and Website. Enter ordinary text, not LaTeX commands or \\ row separators; leave unused inputs empty. The PDF prints each value on its own row, with icons for email, telephone, mobile, fax and website. Email, website and telephone links can be opened from the PDF. Contact name, telephone and email can also be included in electronic XML; the other contact lines are for the visual document.

When an older combined contact field is recognized, LuaBill displays its values in these separate inputs without rewriting or changing the opened document. Unrecognized LaTeX remains in Additional contact text (legacy), shown only when needed, and is preserved until you edit or clear it. Editing the contact inputs and saving uses the structured fields; importing a .bill and saving a new .luabill leaves the original source untouched.

An Electronic address is the invoice recipient/sender endpoint, with its Address scheme. For an email endpoint, the scheme is EM. XRechnung requires electronic endpoints for both parties and seller contact details. Email in the contact field alone is not a substitute for the endpoint fields.

Save your seller details through Settings → Save seller profile, then load that profile for another document. Loading a profile replaces the current seller data and marks the document changed. Review the bank details and any image paths afterward.

5. Items and totals

Use Add row to enter description, quantity, unit price, percentage discount, optional item VAT rate, unit code, optional VAT category and article/SKU. Double-click or select a row and press Enter to edit it; use Remove selected or Delete to remove selected rows. Save or cancel the row editor explicitly.

Use a dot or comma as decimal separator, without thousands separators. Quantity and unit price may contain up to six decimal places; rates and discounts up to four. An empty item VAT rate inherits the document rate. For electronic invoices, use an appropriate unit code, for example C62 for one item. A discount reduces the line amount; do not subtract it again elsewhere.

Check totals validates the current data and shows net, VAT and amount due. It is not the external electronic-invoice validation. PDF and XML generation use the common calculation engine. Inspect mixed VAT groups, discounts and received payments before issuing the document.

6. Remarks and payment text

The Remarks tab contains a label/text table, introductory text, an additional invoice note and optional custom payment terms. Enter plain text; there is no need to type \textbf{...}. Standard label keys such as project are translated into the document language. Labels and short headings before a colon, such as Project:, are printed in bold.

For an existing multilingual note, editing its text changes the current document-language variant and preserves the other variants. Custom prose is not translated automatically. Shared plain-text notes are included in PDF and electronic XML. Imported legacy remarks containing arbitrary LaTeX can remain PDF-only: put essential invoice and payment instructions in the shared plain-text fields.

7. Received advances and final invoices

Enter actual received payments on Received advances, one row per payment and VAT group. Supply the original invoice number/date, receipt date, net amount, VAT amount, VAT rate/category and any exemption reason. All amounts use the current invoice currency. Repeat a reference if a payment spans several VAT groups.

LuaBill adds received gross payments and reduces the amount due. Keep the full goods/services in the Items table; do not subtract the advances again as negative items. The VAT amounts must reconcile with their rates, dates and the tax groups of the final invoice. If you also enter a prepaid total, it must match the detailed sum. For a final invoice without received advances, use a zero prepaid amount. LuaBill does not look up prior invoices or verify bank receipts.

8. Output folder, results, QR, signature and stamp

Initially, projects are proposed under your system Documents folder in LuaBill/Projects; results under LuaBill/Output. Choose your own folders as needed. The Output folder and the option to save results beside the project are settings for this user on this computer, applying to all projects. They are not stored in .luabill. Old project output paths are ignored; existing files are not moved automatically.

Results use the project filename: Invoice-001.pdf, Invoice-001.xml and Invoice-001.validation.xml. Generation can replace the previous results for that project. Archive an issued version before generating revisions that must remain distinguishable.

Successful generation opens the PDF in your default viewer and displays a result panel with paths and Open PDF, Open XML and Open output folder. Automatic opening is controlled by Settings → Open PDF after generation. A changed document or output setting makes the previous result out of date; generate again. The Generation log tab contains detailed messages. If generation fails, a new validated invoice is not published.

Payment QR code (EUR) uses EPC/SEPA payment data and the remaining amount due, with a payment caption. It is available for invoices in EUR with valid IBAN/payment data and a positive payable amount. It is not a general QR payment method for USD or other currencies, and it is not proof of payment. Confirm the bank data and test the code with a compatible banking app.

Select signature and stamp images and their heights, such as 12mm and 35mm. The closing block prints the date/name with an underline, with the signature centered and the stamp overlapping the signature area. Inspect the final PDF with your own image dimensions. These images are graphical marks, not cryptographic signatures. Images are referenced by path rather than embedded in the project: when moving the project, copy the images and select their new paths.

9. Formats and what to send

Electronic export applies to invoices, credit notes and cancellation invoices. Quotations and orders remain PDF business documents. Choosing an electronic format does not turn an offer into an invoice.

Supply number, issue and actual delivery/service dates, both parties and addresses/countries, descriptive invoice lines, currency, correct tax groups and seller tax identification. Depending on the scenario, VAT IDs, exemption reasons and payment information are also required. XRechnung additionally checks buyer reference, both electronic endpoints and seller contact details. Credit/cancellation invoices need their original invoice reference. Examples and validation messages help identify missing fields; sample identifiers must never be used as real ones.

LuaBill validates XML with Mustang. ZUGFeRD additionally passes PDF/A/container checks, and the extracted attachment is compared with the separate XML. Confirm the success message and retain the .validation.xml report. An attachment can also be inspected in a PDF viewer with attachment support; some viewers do not show it. A filename or visual appearance alone does not prove that a PDF is ZUGFeRD. Validation checks document rules, not tax-number registration, invoice-number uniqueness, actual delivery or entitlement to an exemption.

10. Components and installation

Open Help → Components and installation whenever needed. It shows detected paths and Java version, explains missing tools and opens official download pages only when you click a link. After installation choose Check again; if a tool is still missing, restart LuaBill and check again.

• LuaLaTeX and texlua: install MiKTeX or TeX Live; one distribution is enough. Windows: install MiKTeX 64-bit, update it in MiKTeX Console and enable missing-package installation. macOS can use MacTeX; Linux can use its TeX Live packages.
• Ghostscript: official installers. It compresses normal PDF when available and is required for ZUGFeRD PDF/A-3. On macOS/Linux, use the system's package manager.
• Java 17 or newer: Eclipse Temurin. A JRE or JDK works. On Windows choose x64 MSI and enable PATH/JAVA_HOME where offered. Java runs the included Mustang validator/packager for electronic formats; plain PDF does not need it.

The Windows installer includes Python (the program runtime), PySide6/Qt (windows, menus and buttons) and Mustang. You do not install Python or PySide6 separately for that version. Source installations need Python, PySide6 and the supplied Setup script; Windows uses Setup_LuaBill.cmd, macOS/Linux sh Setup_LuaBill.sh. Then use the corresponding Start script. Setup can access the network to install dependencies. Document processing is local; invoice data is not uploaded to an online service.

A compact TeX installation needs LuaLaTeX, fontspec, fontawesome, babel with EN/DE/FR/IT/RU, csquotes, tikz, fancyhdr, enumitem, hyperref, soul, lastpage, textpos, luacode, ltablex, draftwatermark and eso-pic. Install Noto Sans or DejaVu Sans for Unicode text. A component reported as found may still need TeX packages or fonts; the generation log identifies those errors.

11. Saved settings and restoring defaults

On normal exit LuaBill remembers interface language, defaults for new documents (including document language), output location/mode, automatic PDF opening, recent dialog folders, window layout, active tab and table widths. Canceling exit does not save these exit settings. An opened project supplies its own document data. Seller profiles, customer details, document numbers, dates, items and remarks are not substitutes for saving the project.

The store is QSettings("LuaBill", "LuaBill"), with application data in the key preferences/json. It belongs to the current OS user, not the project or program folder. Back it up before resetting. Close all LuaBill windows first so they cannot write the old settings back.

• Windows: in Registry Editor, export and then delete only HKEY_CURRENT_USER\Software\LuaBill\LuaBill. Do not delete the similarly named file-association keys.
• Linux: back up and remove ~/.config/LuaBill/LuaBill.conf, or the corresponding file under $XDG_CONFIG_HOME when that variable is set.
• macOS: Qt uses the user's native Preferences store. Avoid guessing a plist name or deleting unrelated Preferences. With a source installation, use the QSettings reset below; it selects the same application store as LuaBill.

For a source installation, this Python code prints the exact settings location on any OS. Run it in the Python environment where PySide6 is installed, after closing LuaBill:

from PySide6.QtCore import QSettings
settings = QSettings("LuaBill", "LuaBill")
print(settings.fileName())

Back up the displayed store first. Only after the backup, with all LuaBill windows closed, run the following in the same Python session to reset its settings:

settings.clear()
settings.sync()

Restart LuaBill to use defaults. Resetting preferences does not delete projects, seller profiles or generated documents. Your next output folder returns to Documents/LuaBill/Output; check it before generating.

12. Common problems

13. Keyboard shortcuts

Function keys may require Fn on multimedia keyboards. Menus show the shortcuts active on your system.

14. Licenses and acknowledgements

LuaBill — Open Source Business Document Generator
Copyright 2026 Vsevolod Shashkov & Mikhail Shashkov.
LuaBill's own code and documentation are licensed under the Apache License, Version 2.0.

qrencode.lua is a third-party library from speedata/luaqrcode, written by Patrick Gundlach and contributors, copyright 2012–2020. It retains its BSD-3-Clause license and attribution; it was not authored by the LuaBill authors. Other bundled components retain their own licenses. Consult the supplied LICENSE, NOTICE and third-party notices for their full terms.

Back to the first document

Help → Third-party components and sources opens the linked inventory of software, fonts, profiles and artwork. The offline attribution overview also links original licenses and detailed source records.