Mastering report layouts in Odoo 17 is a fundamental skill for any developer or administrator. Whether you are adjusting an invoice to fit a windowed envelope or creating custom labels, the Paper Format (res.paperformat) is the backbone of Odoo’s QWeb PDF engine.
What is a Paper Format?
In Odoo, every PDF report is linked to a paper format. This record defines the physical dimensions of the page, the margins, the orientation, and the resolution (DPI). While Odoo provides standard formats like A4 and US Letter out of the box, specialized business needs often require bespoke configurations.
Key Parameters Explained
| Parameter | Description |
| Name | The label for the format (e.g., "Custom Invoice Format"). |
| Format | Predefined sizes like A4, A3, Letter, Legal. Use 'custom' for specific dimensions. |
| Orientation | Portrait or Landscape. |
| Margins | Top, Bottom, Left, and Right (measured in mm). |
| Header Spacing | The distance from the top of the page to the start of the main body (in mm). |
| DPI | Dots Per Inch. Default is usually 90 or 96. Higher DPI results in smaller, crisper text. |
Technical Implementation (XML)
While you can configure these in the UI, the professional approach is to define them in your module’s data files. This ensures consistency across different environments (Staging, Production).
1. Define the Paper Format
Create an XML file (e.g., data/report_paperformat.xml) and define your record:
<record id="paperformat_euro_low_margin" model="res.paperformat">
<field name="name">Euro Low Margin</field>
<field name="default" eval="True" />
<field name="format">A4</field>
<field name="page_height">0</field>
<field name="page_width">0</field>
<field name="orientation">Portrait</field>
<field name="margin_top">10</field>
<field name="margin_bottom">10</field>
<field name="margin_left">7</field>
<field name="margin_right">7</field>
<field name="header_line" eval="False" />
<field name="header_spacing">15</field>
<field name="dpi">90</field>
</record>
2. Link the Format to a Report
Once the format is defined, you must associate it with a specific report action using the paperformat_id field.
<record id="action_report_custom_invoice" model="ir.actions.report">
<field name="name">Custom Invoice</field>
<field name="model">account.move</field>
<field name="report_type">qweb-pdf</field>
<field name="report_name">my_module.report_invoice_template</field>
<field name="print_report_name">'Invoice - %s' % (object.name)</field>
<field name="paperformat_id" ref="my_module.paperformat_euro_low_margin"/>
</record>
Understanding the "Header Spacing" Trap
One of the most common issues in Odoo reporting is the overlap between the header and the body.
- Margin Top: This defines where the Header starts.
- Header Spacing: This defines where the Body starts.
If your header_spacing is smaller than your margin_top, your body text will likely bleed into your header. As a rule of thumb, always keep header_spacing at least 5-10mm larger than margin_top to account for the height of the header content itself.
UI-Based Configuration
If you prefer a "No-Code" approach or need to make a quick fix on a production server:
- Activate Developer Mode.
- Navigate to Settings > Technical > Reporting > Paper Format.
- Modify an existing format or create a new one.
- To apply it, go to Settings > Technical > Reporting > Reports, search for your report, and select your new format in the Paper format field.