NetBox Tenant Switcher

[!NOTE] There's a newer, more capable successor: netbox-scope-switcher. It generalizes this plugin — tenant becomes just one of any number of configurable, grouped scope dimensions (region, site, tag, …) whose filters cascade on each other. If you're starting fresh, prefer scope-switcher; this plugin remains available for tenant-only setups.

Pick a tenant once, and every list in NetBox shows only that tenant's objects.

netbox-tenant-switcher adds a searchable tenant selector to the top navigation bar — rendered inside the field, just like NetBox's global search box. Choose a tenant and, as you move between sections (Devices, Prefixes, VLANs, Sites, Racks, …), each list view is automatically scoped to that tenant. Choose "— All tenants —" to clear the scope.

It's ideal for MSPs, multi-customer labs, and anyone who spends the day working inside one tenant at a time and doesn't want to add a tenant filter on every page.

Screenshots

The tenant selector sits in the top navigation bar, rendered inside the field like NetBox's global search.

Open the dropdown to multi-select tenants and type to filter instantly; selected tenants float to the top.

Chosen tenants are listed comma-separated in the field and persist across the session.

Every list view (Devices, Prefixes, VLANs, …) is automatically scoped to the selected tenants.

Features

• Multi-select tenant switcher in the navbar with a checkbox per tenant and instant client-side search — no external JS dependencies.
• Selected tenants are shown comma-separated in the field, truncated with an ellipsis to fit the header; the field width adapts to the viewport and never overlaps the global search box.
• Selected tenants float to the top when the dropdown opens; the list is ordered by name.
• Selection persists in the session; no models, no migrations.
• Automatically scopes every object list view whose filterset supports a tenant filter, by appending ?tenant_id=<id> (once per selected tenant, so multiple tenants are OR-combined).
• Non-tenancy models (Manufacturers, Device Types, …) and detail views are left untouched.
• Permission-aware: the dropdown only lists tenants the user may view, and a tenant can't be selected unless the user has view access to it.
• Only ever narrows results — NetBox object permissions still apply on top.

Compatibility

Developed and verified against NetBox 4.6. It uses only stable plugin APIs (PluginTemplateExtension.navbar() / head(), plugin middleware) and is expected to work on nearby 4.x releases; the CI matrix in .github/workflows/ci.yml is where additional versions should be validated.

Dependencies

• NetBox ≥ 4.6 (provides Django, Tom Select, and the tenancy models).
• No additional Python packages, external services, or other plugins required.

Installation

1. Install the package into NetBox's Python environment:

   source /opt/netbox/venv/bin/activate
   pip install netbox-tenant-switcher
   

2. Enable it in configuration.py:

   PLUGINS = [
       "netbox_tenant_switcher",
   ]
   

3. Restart NetBox:

   sudo systemctl restart netbox netbox-rq
   

No database migrations are required.

Docker (netbox-docker)

See deploy/ for a ready-to-use Dockerfile-Plugins, docker-compose.override.yml, and plugins.py. In short: drop the project under plugins/plugin-src/, add the plugin to configuration/plugins.py, then:

docker compose build netbox
docker compose up -d

Configuration

None. The plugin works out of the box; there are no PLUGINS_CONFIG settings.

How it works

• Navbar widget (template_content.py) — a PluginTemplateExtension renders a small, dependency-free multi-select (checkbox list + instant search) via the navbar() hook; styling is injected through head(). It stays in one line with the selected tenants comma-separated and ellipsis-truncated.

• Set endpoint (views.py) — GET /plugins/tenant-switcher/set/?tenant=<id>&tenant=<id>&next=<path> stores the chosen tenants in the session and redirects back. next is validated against the current host (no open redirects) and every tenant id is checked against the user's view permission.

• Middleware (middleware.py) — for ObjectListView pages whose filterset exposes a tenant_id filter, it appends one ?tenant_id=<id> per selected tenant when no explicit tenant filter is already present.

  Design note: scoping is done by URL rewriting rather than by patching every queryset. This keeps the plugin decoupled from core views, applies uniformly across DCIM/IPAM/etc., and leaves the applied filter visible and removable in the UI.

Support

• Issues / bugs / features: GitHub Issues — https://github.com/Du10777/netbox-tenant-switcher/issues
• Questions: GitHub Discussions, or the NetDev Community Slack (#netbox).

Contributing

PRs welcome. Run the test suite the way NetBox does — see .github/workflows/ci.yml (checkout NetBox, install the plugin, then python netbox/manage.py test netbox_tenant_switcher).

License

Apache-2.0 — matching NetBox itself. The icon in docs/img/ is released under CC BY 4.0.