Scapy: packet crafting in Python, from a REPL to a script

What Scapy replaces, and who ends up using it

Most packet tools give you a fixed command with fixed flags. Scapy gives you a packet object. You describe the layers you want, and the library fills in defaults that work, which is the design goal the README states: "It is designed to allow fast packet prototyping by using default values that work." That single decision explains both its reach and its rough edges.

The README claims it can stand in for hping, arpspoof, arping, tcpdump, wireshark and p0f, and for "85% of nmap". Treat that as a description of overlap, not of equivalence. What Scapy actually covers is the case where the tool you need does not exist yet: a VLAN tag stacked under a crafted ARP reply, an 802.11 frame that a driver would refuse to emit, a decoder for a protocol that only your team speaks. The intended audience is developers, security researchers, network engineers and people writing tests, which matches the classifiers in pyproject.toml (Information Technology, Science/Research, Telecommunications Industry).

It is a poor fit for someone who wants a menu-driven scanner. If your task is "find every open port on a /16", reach for nmap and read its output. Scapy will do the job, slowly, and you will spend the afternoon writing the loop.

Packets as Python objects: the / operator and the sr family

The core mechanism is layer stacking with the / operator. IP(dst="github.com")/ICMP() builds one object whose payload is another object. Fields you do not set take defaults; fields you do set are encoded on the wire. Decoding runs the same model in reverse, so a captured frame comes back as a stack of layer objects you can index and inspect.

Sending is split by whether you want an answer. sr1() sends one packet and waits for the first reply, sr() returns answered and unanswered lists, send() fires without listening. This is where Scapy differs from a capture tool: it is a request/reply engine as much as a sniffer, and the README lists "match requests and replies" as a first-class capability. Storage and replay go through pcap files, so a session can be written out and read back.

The README's own shell demo shows the shape of a session: build the packet, call sr1(), then read a field off the reply. The reply object is indexed by layer, so r[IP].src gives you the source address without parsing bytes by hand. That indexing is the whole ergonomic argument for the library.

Installing Scapy and sending your first packet

The README gives a clone-based route for running the shell. It states that on Linux and BSD-like systems Scapy works without any external Python modules, and that Windows needs mandatory dependencies described in the installation page of the documentation.

git clone https://github.com/secdev/scapy
cd scapy
./run_scapy

run_scapy starts the interactive shell. There is also a console entry point declared in pyproject.toml, scapy = "scapy.main:interact", so an installed copy exposes a scapy command. The package is published on PyPI, and the README carries a PyPI version badge, so pip install scapy is the normal path when you want the library rather than a checkout. The project metadata declares requires-python = ">=3.7, <4".

Once the shell is up, the README's demo is the shortest real use. It sends an ICMP Echo Request and prints the source address of the reply:

p = IP(dst="github.com")/ICMP()
r = sr1(p)
r[IP].src

The shell prints emission progress and a summary line such as how many packets were received versus how many answers were obtained, then the final expression evaluates to the responder's IP as a string. Sending raw packets needs the privileges your platform requires for raw sockets; the README's demo invokes the shell with sudo, which is the honest signal about permissions.

For plotting and cryptographic features the README points at optional Python modules such as matplotlib and cryptography, and pyproject.toml defines an optional dependency group named cli that pulls in ipython. Installing the base package does not install those.

Where Scapy stops being the right tool

Scapy operates in user space through Python. Every packet you build is a Python object graph, and every packet you capture is decoded into one. That is the price of the flexibility, and it shows up in three places.

First, throughput. A sniffer that decodes in Python will not keep up with a saturated high-rate link the way a C capture path does. If your job is to record everything on a 10G interface, Scapy is the wrong layer; capture with a dedicated tool and analyze the pcap afterwards.

Second, platform behaviour. The README is explicit that Windows needs extra mandatory dependencies, and it does not promise that every link-layer feature behaves identically across Linux, OSX, *BSD and Windows. Injecting 802.11 frames is the clearest example: it depends on the driver and the OS, not on Scapy alone. A script that works on a Linux laptop with a monitor-mode adapter may not work elsewhere, and the README does not document rollback or per-platform feature matrices.

Third, the 85% claim about nmap cuts both ways. The remaining 15% includes the parts that make nmap worth using: its service and version detection database, its timing templates, its output formats. Rebuilding those on top of Scapy is a project, not a configuration change.

Scapy against tcpdump and Wireshark

tcpdump and Wireshark are capture and inspection tools. You give them a filter, they give you packets and a display. Scapy is a construction and scripting environment that also captures. The difference is direction of control: with tcpdump you ask the kernel for traffic matching an expression, while with Scapy you decide what goes on the wire and then decide what to do with whatever comes back.

A concrete consequence: with tcpdump you can run a BPF filter and stream results to a file with almost no CPU per packet. With Scapy you can write a callback that inspects each decoded packet and, in the same script, send a crafted response based on what it saw. That loop (observe, decide, emit) is awkward to express with tcpdump plus a shell pipeline, and it is the reason Scapy exists. The README frames this as combining techniques, and gives VLAN hopping combined with ARP cache poisoning as an example.

If you only need to look at packets, Wireshark's dissectors are deeper and its UI is the point. If you need to generate packets that no ordinary socket API will let you generate, Scapy is the shorter path.

Licence, maintenance and what an upgrade costs

Scapy's code, tests and tools are licensed under GPL v2, and pyproject.toml states license = "GPL-2.0-only". The documentation is licensed separately under CC BY-NC-SA 2.5, with the logo excluded. The practical implication, stated as a fact rather than as legal advice: GPL-2.0-only is a copyleft licence, so distributing a product that links Scapy brings the licence's obligations with it. If your product is closed source, that is a question for your own counsel before you write the import.

The repository is not archived, and the last push was on 2026-09-20. Releases are infrequent and large: v2.6.0 in September 2024, v2.6.1 in November 2024, and v2.7.0 in December 2025. Between releases, master moves. That has an upgrade cost worth naming: if you depend on a behaviour that only landed after the last tag, you are tracking master, and the project's own setup.py comments describe non-standard versioning machinery built around a scapy/VERSION file, which is a hint that version handling has been fiddly historically. Pin a released version unless you need a specific fix from master.

The declared Python floor is 3.7 and the ceiling is below 4, and pyproject.toml lists classifiers through Python 3.14. Dropping support for an old interpreter is a normal release-time event, so pinning also protects you from a floor that moves.

Editorial conclusion

Adopt Scapy when you need to build packets that a normal stack will not produce, or to script capture and decode inside Python. Do not adopt it as a drop-in replacement for a full port scanner or for high-throughput traffic analysis, and do not link it into closed-source products without reading the GPL-2.0 terms. Before committing, verify on your own kernel which link-layer backend is selected, whether you need root or CAP_NET_RAW, and whether your target Python version is inside the >=3.7, <4 range declared in pyproject.toml.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. secdev/scapy on GitHub