Extending Netbox Without Forking It: Custom Fields in Practice

The problem: Netbox almost fits your data

Every team that adopts Netbox eventually hits the same wall. The built-in data model covers devices, racks, sites, IP addresses, and cables beautifully — but your organization also needs to track things Netbox never heard of. Maintenance contract expiry dates. Asset tag numbers from finance. The name of the vendor engineer who last touched a chassis.

The tempting options are both bad: fork the codebase and add real model fields (you now own every future upgrade), or stuff the data into the description field as free text (you can no longer filter, report, or validate anything). Custom Fields are the supported middle path, and they are good enough that most teams never need anything else.

What Custom Fields actually are

A Custom Field is an administrator-defined attribute that Netbox attaches to an existing model — devices, sites, prefixes, virtual machines, circuits, and most other object types. You define it once under Customization → Custom Fields (in older releases, Extras → Custom Fields), pick a type, and assign it to one or more models. From that point on, the field appears in the object's edit form, in the REST API under a custom_fields object, and in the filter UI.

The available types cover most real needs: text, long text, integer, decimal, boolean, date, URL, JSON, selection (single or multiple choice from a defined list), and object references to other Netbox models. Selection fields deserve special mention — by constraining values to a defined choice set, you get data quality that free text never gives you. If you are recording something like "support tier", use a selection field, not a text field, or you will end up with "Gold", "gold", and "GOLD" in the same column.

A worked example: maintenance expiry tracking

Say you want a report of devices whose maintenance contracts expire in the next 30 days. Here is the whole lifecycle.

1. Create the field. In the Netbox UI as an administrator, go to Customization → Custom Fields → Add. Set the name to maintenance_expiry, the label to "Maintenance Expiry", the type to Date, and assign it to DCIM → Device. Save. The field now appears on every device's edit form.

2. Populate it via the API. For bulk data entry — say, importing from your procurement system — the REST API is the sane path. Run this from any host that can reach your Netbox instance, using a token with write permission on devices:

curl -X PATCH \
  -H "Authorization: Token <your-api-token>" \
  -H "Content-Type: application/json" \
  https://netbox.example.com/api/dcim/devices/1234/ \
  -d '{"custom_fields": {"maintenance_expiry": "2027-05-30"}}'

Replace 1234 with a real device ID and the token placeholder with a token that has device write rights. Note that custom field values live under the custom_fields key — patching that key merges your values; it does not wipe other custom fields on the object.

3. Verify the write. Read the device back and confirm the value persisted:

curl -s -H "Authorization: Token <your-api-token>" \
  https://netbox.example.com/api/dcim/devices/1234/ | jq '.custom_fields'

You should see "maintenance_expiry": "2027-05-30" in the output. If the key is missing entirely, the field definition was probably not assigned to the Device model — check that first.

4. Filter on it. Custom fields are filterable in both the UI and the API. To find devices expiring before a date:

curl -s -H "Authorization: Token <your-api-token>" \
  "https://netbox.example.com/api/dcim/devices/?cf_maintenance_expiry__lte=2026-11-15"

The cf_ prefix tells Netbox to filter on a custom field, and __lte is a lookup expression (less than or equal). In the UI, you can build the same condition in the device filter form and save it as a reusable filter for your renewal report. Compute the cutoff date in whatever script drives the report — Netbox filters take literal dates, not relative expressions like "30 days from now".

The trade-offs you should know before going all-in

Custom fields are not free, and the costs show up late if you ignore them early.

They are not version-controlled. Built-in models change through Netbox's managed migrations; your custom field definitions live only in the database. If you run multiple Netbox environments (dev, staging, prod), you must replicate field definitions yourself — either by hand, by exporting/importing the definitions as data, or by scripting their creation through the API. Teams that skip this end up with a staging environment that silently lacks half the fields production has.

Performance degrades with volume and size. Every custom field on a model adds work to each API serialization of that model. A handful of scalar fields is fine. Dozens of fields, or fields holding large JSON blobs, will measurably slow list API responses and bulk operations. Keep JSON fields small and structured; if you are storing kilobytes of nested data per object, that data probably belongs in a dedicated system linked by URL instead.

Upgrades need a sanity check. Custom fields are a stable, supported feature, but major Netbox upgrades occasionally change surrounding behavior — filter syntax, API representation, or UI placement. The practical habit: after any upgrade, spot-check that your fields still render, that a PATCH to custom_fields still works, and that your saved filters still return the expected objects. This takes ten minutes and catches problems before your reporting pipeline does.

Deletion is destructive. Removing a custom field definition deletes its data on every object. If you are retiring a field, export the data first — a simple API query dumping id and the field value to CSV is enough insurance.

Where to start

Pick one piece of metadata your team currently tracks in a spreadsheet next to Netbox — maintenance expiry and asset tags are the usual suspects — and model it as a properly typed custom field this week. Populate it through the API, build one saved filter on top of it, and verify the round trip with the read-back shown above. If the filter returns exactly the devices you expect, you have replaced a spreadsheet with a queryable source of truth, and Netbox remains a stock, upgradable install. That is the whole point.