NFStream: Network Flow Analysis from Live Traffic and PCAP with Python

What NFStream does and who it is for

Network traffic analysis often starts with a PCAP file or a live network interface and ends with a structured table of flows: each row summarizing a bidirectional connection between two endpoints, with timing, packet counts, byte counts, and application-layer metadata. The tooling to go from raw packets to that table has historically required C-based libraries (libpcap, nDPI) with Python wrappers that each project assembled differently, making experiments hard to reproduce across teams.

NFStream exists to be a unifying framework for network data analytics. The README describes its goal: making machine learning approaches for network traffic management reproducible and deployable by ensuring models are trained with the same feature computation logic. The intended users are network researchers building traffic classifiers, security analysts processing network logs, and operations engineers who need programmatic flow data for monitoring. The library processes both live capture from a network interface and offline analysis from PCAP files through the same NFStreamer API.

The NFStreamer: one API for live and offline traffic

NFStream's primary interface is the NFStreamer class. The source parameter accepts either a path to a PCAP file or the name of a live network interface. All other parameters have defaults, making it possible to get a working streamer with a single line. The README provides the full parameter list with defaults:

from nfstream import NFStreamer
# We display all streamer parameters with their default values.
# See documentation for detailed information about each parameter.
# https://www.nfstream.org/docs/api#nfstreamer
my_streamer = NFStreamer(source="facebook.pcap", # or live network interface
                         decode_tunnels=True,
                         bpf_filter=None,
                         promiscuous_mode=True,
                         snapshot_length=1536,
                         idle_timeout=120,
                         active_timeout=1800)

The idle_timeout and active_timeout parameters control when a flow is considered complete. A flow with no new packets for idle_timeout seconds is expired. A flow that has been active for active_timeout seconds is also expired, even if still receiving packets. These defaults (120 and 1800 seconds) are configurable per use case. The bpf_filter parameter accepts Berkeley Packet Filter expressions to restrict which packets are processed.

Installing NFStream and the Windows requirement

NFStream is available on PyPI:

pip install nfstream

The library requires Python 3.9 or later. Key runtime dependencies include cffi (for the CFFI-based computation engine that wraps the C libraries), psutil (for system-level socket information), dpkt (for packet decoding), numpy, and pandas. The pyproject.toml pins minimum versions: cffi>=1.15.0, psutil>=5.8.0, dpkt>=1.9.7, numpy>=1.19.5, and pandas>=1.1.5. On Linux, the AF_PACKET_V3/FANOUT socket interface and multiprocessing support provide high-throughput capture.

The README includes a specific note for Windows: NFStream does not include capture drivers on Windows due to license restrictions. Npcap drivers must be installed before NFStream can capture live traffic. If Wireshark is already installed, Npcap is already present. Users working only with PCAP files (no live capture) may not need to install Npcap separately. The library also supports PyPy3 for scenarios where higher throughput from the Python layer is needed.

Each flow as a typed NFlow object

When NFStreamer processes traffic, each expired bidirectional flow is yielded as an NFlow object. The object carries connection-level metadata (source and destination IP addresses, MAC addresses, OUI prefixes, ports, protocol, IP version, VLAN ID, tunnel ID) alongside timing fields. From the README example:

NFlow(id=0,
      expiration_id=0,
      src_ip='192.168.43.18',
      src_mac='30:52:cb:6c:9c:1b',
      src_oui='30:52:cb',
      src_port=52066,
      dst_ip='66.220.156.68',
      dst_mac='98:0c:82:d3:3c:7c',
      dst_oui='98:0c:82',
      dst_port=443,
      protocol=6,
      ip_version=4,
      vlan_id=0,
      tunnel_id=0,
      bidirectional_first_seen_ms=1472393122365,
      bidirectional_last_seen_ms=1472393123665,
      bidirectional_duration_ms=1300)

The full NFlow field set includes bidirectional statistical features (packet sizes, inter-arrival times) not shown in this excerpt. The README links to the NFlow API documentation at https://www.nfstream.org/docs/api#nflow for the complete field reference. Fields with the bidirectional_ prefix aggregate traffic in both directions.

nDPI for encrypted application identification

One of NFStream's most practically useful features is its encrypted application identification. The README describes this as deep packet inspection based on nDPI, an open-source DPI library. nDPI can identify the application behind a TLS, QUIC, or SSH connection without decrypting the payload, using fingerprinting of handshake metadata, certificate fields, and traffic patterns.

The README lists the identification targets as: reliable encrypted application identification and metadata fingerprinting including TLS, SSH, DHCP, and HTTP. This means an NFStream flow record can include the application label (for example, identifying port-443 traffic as belonging to a specific service) even when the payload is encrypted. The accuracy of this identification depends on nDPI's signature database and the characteristics of the traffic. Novel or proprietary protocols that nDPI does not have signatures for will be classified as unknown. The nDPI dependency is bundled with NFStream's distribution, so users do not need to install nDPI separately.

NFPlugins: extending flow features with Python

NFStream's extension mechanism is the NFPlugin system. A plugin is a Python class that the streamer calls at defined points in the flow lifecycle: when a flow is created, when a new packet arrives, and when a flow expires. This allows developers to add custom features to every flow record without modifying the NFStream core.

The README describes the plugin API as allowing the creation of a new flow feature within a few lines of Python. A plugin that counts packets matching a specific payload pattern, flags flows with unusual inter-arrival time distributions, or queries an external reputation service can all be implemented this way. The machine learning use case is particularly strong here: a plugin can apply a trained classifier to each flow's feature vector in real time as packets arrive, enabling live traffic classification. The same plugin code that runs on historical PCAP data for training can be deployed on live traffic for inference, which is the reproducibility goal the README describes.

System visibility: process-to-socket attribution

Beyond network-layer features, NFStream can attribute flows to specific processes running on the monitored machine. The README describes this as probing the monitored system's kernel to obtain information on open Internet sockets and collecting guaranteed ground-truth at the application level: process name and PID. This feature operates only when NFStream is capturing traffic on the local machine (not analyzing a PCAP from a remote system), and it requires sufficient permissions to query the kernel socket table.

Process attribution is valuable for endpoint security monitoring: instead of identifying a connection only by its IP address and port, an analyst can see that a specific process initiated it. Combined with nDPI's application identification, this provides two independent signals: the protocol/application recognized by DPI, and the process name reported by the OS. The psutil dependency handles the kernel socket queries on Linux, macOS, and Windows.

Pandas and CSV export, and LGPL-3.0 license

NFStream integrates directly with pandas for analysis. The streamer can export flows to a pandas DataFrame or a CSV file, which makes it compatible with the standard Python data science toolchain. The examples directory contains csv_generator.py, flow_printer.py, and wfeatures_pandas.py as reference implementations. A Binder live notebook for interactive exploration is linked from the README.

The last push was on 2026-09-14. Version 6.6.0 was released on 2026-02-15, and version 6.6.1 is listed in pyproject.toml. The license is LGPL-3.0. Under LGPL terms, using NFStream as a library in proprietary software does not require releasing the proprietary code, as long as the NFStream library itself is not modified. Modifications to the NFStream library must be released under LGPL-3.0. The LGPL is a common license choice for utility libraries specifically to permit this pattern. The cibuildwheel configuration in pyproject.toml confirms that platform-specific wheels are built for distribution, covering Linux, macOS, and Windows builds.

Editorial conclusion

NFStream is a strong fit for network security researchers, machine learning engineers building traffic classifiers, and operations teams who need programmatic access to labeled flow records from either live capture or historical PCAP files. The nDPI dependency for encrypted traffic identification adds capability but also a build dependency that complicates installation on unusual platforms. The LGPL-3.0 license permits proprietary applications to use the library without releasing source code, as long as the library itself is not modified. Before deploying on Windows, install Npcap drivers as the README requires; without them, live capture will not work.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. nfstream/nfstream on GitHub
3. Project website
4. README
5. Releases