Contract plugin
NetBox plugin to manage contracts.
- Free software: MIT
- Documentation: https://mlebreuil.github.io/netbox-contract/
Features
The plugin adds contracts and invoices model to NetBox.
It allows to link contract with objects.
Each contract is described by contract lines (one-time, recurring or usage-based, through units).
Invoices are linked with contracts; their amount is proposed and their invoice lines are generated from the contract lines.
Accounting dimensions can be linked with contract lines and invoice lines.
Compatibility
| NetBox Version | Plugin Version |
|---|---|
| 4.1 | 2.2 |
| 4.2 | 2.3 |
| 4.3 | 2.4 |
| 4.4 | 2.4 |
| 4.5 | 2.4 |
| 4.6 | 2.4, 2.5 |
Version 2.5 requires NetBox 4.6 or later.
Installing
Activate venv
To ensure our plugin is accessible to the NetBox installation, we first need to activate the Python virtual environment that was created when we installed NetBox. To do this, determine the virtual environment's path (this will be /opt/netbox/venv/ if you use the documentation's defaults) and activate it:
$ source /opt/netbox/venv/bin/activate
Install the package
$ python3 -m pip install netbox-contract
Configure NetBox
Finally, we need to configure NetBox to enable our new plugin. In the NetBox installation directory, open netbox/netbox/configuration.py and locate the PLUGINS parameter; it should be an empty list. (If it's not yet defined, go ahead and create it.) Add the name of our plugin to this list:
# configuration.py
PLUGINS = [
'netbox_contract',
]
Customize the plugin
The following configuration items can be set:
# configuration.py
PLUGINS_CONFIG = {
'netbox_contract': {
'top_level_menu': True,
'mandatory_contract_fields': [],
'hidden_contract_fields': [],
'mandatory_invoice_fields': [],
'hidden_invoice_fields': [],
'mandatory_dimensions': [],
'supported_models': [
'circuits.circuit',
'circuits.virtualcircuit',
'dcim.site',
'dcim.device',
'dcim.rack',
'virtualization.virtualmachine',
'virtualization.cluster',
'ipam.ipaddress',
'ipam.prefix',
],
'contract_assignments_display': 'both', # options: 'tab', 'inline', 'both'
'show_deprecated_fields': False,
}
}
- top_level_menu : If "Contracts" appears under the "Plugins" menu item or on its own
- contract_assignments_display:
'tab'- only the Contracts view tab is visible on the related object page.'inline'- only the inline contract assignments table is shown in object detail; the Contracts tab is hidden.'both'- both tab and inline table are shown (default behavior).
- default_accounting_dimensions: The accounting dimensions which will appear in the field' background when empty. Note that accounting dimensions are now managed as individual objects. The use of this field is deprecated.
- mandatory_contract_fields, mandatory_invoice_fields: Fields which are not required by default and can be set as such. The list of fields is at the bottom of the contract import form.
- hidden_contract_fields, hidden_invoice_fields: List of fields to be hidden. Fields should not be required to be hidden. A deprecated field that is not shown is ignored, with a warning in the log.
- show_deprecated_fields: show the deprecated contract cost fields (monthly, yearly and non-recurring costs, replaced by contract lines) in the contract form, detail page and tables, and allow creating new invoice templates. Default:
False.
Customize the plugin fields choices
Internal party reference the legal entity of your organization that is a party to the contract.
The first currency will also be the default currency for contracts.
# configuration.py
FIELD_CHOICES = {
'netbox_contract.Contract.internal_party': (
('default', 'Default entity', 'green'),
('entity1', 'Entity 1', 'green'),
('entity2', 'Entity 2', 'yellow'),
),
'netbox_contract.Contract.currency': (
('usd', 'USD'), # 1st position is the default currency
('eur', 'EUR'),
('chf', 'CHF'),
('pln', 'PLN'),
),
'netbox_contract.Contract.status': (
('active', 'Active', 'green'),
('canceled', 'Canceled', 'red'),
)
'netbox_contract.Invoice.status': (
('draft', 'Draft', 'yellow'),
('posted', 'Posted', 'green'),
('canceled', 'Canceled', 'red'),
)
}
Run database migrations
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py migrate
Upgrading to version 2.5
The migration to version 2.5 converts the monthly, yearly and non-recurring costs and the invoice templates of existing contracts into contract lines, and prints a report of the judgement calls it made (for example an invoice template whose total differs from the recurring cost). Invoices, invoice lines, invoice templates and the deprecated fields are not changed. The conversion can be run again at any time; contracts that already have contract lines are skipped:
(venv) $ python3 manage.py convert_contract_lines
The custom script "Report currency mismatches" (in scripts/netbox-contract.py) lists existing records whose currency does not match their contract or invoice, without changing them.
1 maintainer
Metadata
1 maintainer
Release files for netbox-contract 2.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| netbox_contract-2.5.0.tar.gz | 563.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| netbox_contract-2.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 703.4 kB
Release files / netbox_contract-2.5.0.tar.gz
| Download URL | netbox_contract-2.5.0.tar.gz |
|---|---|
| Size | 563.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
acb5b0ca79b111e6ce2de9996069e9dccbd6eb3d0eb7a9eef1b0eed440f36322
|
|
BLAKE2b-256 checksum How to use checksums |
bd248d35305b77abb63d81ddcf3e59d9880d0f88a8454cd4924b23a57f40f072
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / netbox_contract-2.5.0-py3-none-any.whl
| Download URL | netbox_contract-2.5.0-py3-none-any.whl |
|---|---|
| Size | 139.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fe10da8b36a98f48b953fdbc30f4c3063e3fc7bbd757b30a00d40f61aa4a3e0d
|
|
BLAKE2b-256 checksum How to use checksums |
38e24f806089b08839539bdc1b9cae30df2a990eb3fe8134fab885721046150e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency log
