Skip to main content

Django PostgreSQL netfields implementation

Project description

This project is an attempt at making proper PostgreSQL net related fields for Django. In Django pre 1.4 the built in IPAddressField does not support IPv6 and uses an inefficient HOST() cast in all lookups. As of 1.4 you can use GenericIPAddressField for IPv6, but the casting problem remains.

In addition to the basic IPAddressField replacement a CIDR and a MACADDR field have been added. This library also provides a manager that allows for advanced IP based lookup directly in the ORM.

In Python, the values of the IP address fields are represented as types from the ipaddress module. In Python 2.x, a backport is used. The MAC address field is represented as an EUI type from the netaddr module.


Current version of code is targeting Django >= 1.8 support, as this relies heavily on ORM internals and supporting multiple versions is especially tricky.


$ pip install django-netfields

Getting started

Make sure netfields is in your PYTHONPATH and in INSTALLED_APPS.

InetAddressField will store values in PostgreSQL as type INET. In Python, the value will be represented as an ipaddress.ip_interface object representing an IP address and netmask/prefix length pair unless the store_prefix_length argument is set to False, in which case the value will be represented as an ipaddress.ip_address object.

from netfields import InetAddressField, NetManager

class Example(models.Model):
    inet = InetAddressField()
    # ...

    objects = NetManager()

CidrAddressField will store values in PostgreSQL as type CIDR. In Python, the value will be represented as an ipaddress.ip_network object.

from netfields import CidrAddressField, NetManager

class Example(models.Model):
    inet = CidrAddressField()
    # ...

    objects = NetManager()

MACAddressField will store values in PostgreSQL as type MACADDR. In Python, the value will be represented as a netaddr.EUI object. Note that the default text representation of EUI objects is not the same as that of the netaddr module. It is represented in a format that is more commonly used in network utilities and by network administrators (00:11:22:aa:bb:cc).

from netfields import MACAddressField, NetManager

class Example(models.Model):
    inet = MACAddressField()
    # ...

For InetAddressField and CidrAddressField, NetManager is required for the extra lookups to be available. Lookups for INET and CIDR database types will be handled differently than when running vanilla Django. All lookups are case-insensitive and text based lookups are avoided whenever possible. In addition to Django’s default lookup types the following have been added:

is contained within the given network
is contained within or equal to the given network
contains the given address
contains or is equal to the given address/network
contains or contained by the given address
matches the given address family
matches the host part of an address regardless of prefix length
matches the prefix length part of an address

These correspond with the operators and functions from

CidrAddressField includes two extra lookups (these will be depreciated in the future by __prefixlen):

Maximum value (inclusive) for CIDR prefix, does not distinguish between IPv4 and IPv6
Minimum value (inclusive) for CIDR prefix, does not distinguish between IPv4 and IPv6

Database Functions

Postgres network address functions are exposed via the netfields.functions module. They can be used to extract additional information from these fields or to construct complex queries.

from django.db.models import F

from netfields import CidrAddressField, NetManager
from netfields.functions import Family, Masklen

class Example(models.Model):
    inet = CidrAddressField()
    # ...

ipv4_with_num_ips = (
        num_ips=2 ** (32 - Masklen(F('inet')))  # requires Django >2.0 to resolve

CidrAddressField and InetAddressField Functions

Postgres Function Django Function Return Type Description
abbrev(T) Abbrev TextField abbreviated display format as text
broadcast(T) Broadcast InetAddressField broadcast address for network
family(T) Family IntegerField extract family of address; 4 for IPv4, 6 for IPv6
host(T) Host TextField extract IP address as text
hostmask(T) Hostmask InetAddressField construct host mask for network
masklen(T) Masklen IntegerField extract netmask length
netmask(T) Netmask InetAddressField construct netmask for network
network(T) Network CidrAddressField extract network part of address
set_masklen(T, int) SetMasklen T set netmask length for inet value
text(T) AsText TextField extract IP address and netmask length as text
inet_same_family(T, T) IsSameFamily BooleanField are the addresses from the same family?
inet_merge(T, T) Merge CidrAddressField the smallest network which includes both of the given networks

MACAddressField Functions

Postgres Function Django Function Return Type Description
trunc(T) Trunc T set last 3 bytes to zero


As of Django 2.2, indexes can be created for InetAddressField and CidrAddressField extra lookups directly on the model.

from django.contrib.postgres.indexes import GistIndex
from netfields import CidrAddressField, NetManager

class Example(models.Model):
    inet = CidrAddressField()
    # ...

    class Meta:
        indexes = (
                fields=('inet',), opclasses=('inet_ops',),

For earlier versions of Django, a custom migration can be used to install an index.

from django.db import migrations

class Migration(migrations.Migration):
    # ...

    operations = [
        # ...
            "CREATE INDEX app_example_inet_idx ON app_example USING GIST (inet inet_ops);"
        # ...


Similar projects tries to solve some of the same issues as this library. However, instead of supporting just postgres via the proper fields types the ipyfield currently uses a VARCHAR(39) as a fake unsigned 64 bit number in its implementation.


Main repo was originally kept Late April 2013 the project was moved to to pass the torch on to someone who actually uses this code actively :-)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-netfields, version 1.2.4
Filename, size File type Python version Upload date Hashes
Filename, size django-netfields-1.2.4.tar.gz (20.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page