# Binwalk v3 - Fast Firmware Analysis with v2 API Compatibility
[](https://badge.fury.io/py/binwalk3)
[](https://pypi.org/project/binwalk3/)
[](https://opensource.org/licenses/MIT)
A Python package that provides binwalk v2's familiar API while using the blazing-fast binwalk v3 Rust binary under the hood. Get 2-5x faster firmware analysis with zero code changes!
## Features
✨ **Drop-in Replacement**: Same API as binwalk v2 - just change your import!
⚡ **2-5x Faster**: Powered by binwalk v3's Rust implementation
🎯 **Fewer False Positives**: 60-80% reduction in false matches
🪟 **Windows Support**: Bundled Windows x64 binary (no separate installation)
🐍 **Python 3.8+**: Modern Python with type hints
📦 **Zero Runtime Dependencies**: Pure Python package
## Installation
```bash
pip install binwalk3
```
That's it! The Windows binary is included. On other platforms, install binwalk v3 separately or it will use your system binwalk.
## Quick Start
```python
import binwalk
# Scan a firmware file
for module in binwalk.scan('firmware.bin'):
for result in module:
print(f"Found {result.description} at {result.offset:#x}")
```
### Extract Files
```python
import binwalk
# Extract embedded files
binwalk.scan('firmware.bin', extract=True)
```
### Entropy Analysis
```python
import binwalk
# Analyze entropy
results = binwalk.scan('firmware.bin', entropy=True)
```
### Using the Modules Class
```python
from binwalk import Modules
# Advanced usage with Modules class
modules = Modules()
results = modules.execute('firmware.bin', extract=True, matryoshka=True)
for module in results:
print(f"Scanned: {module.file}")
print(f"Found {len(module.results)} results")
for result in module:
print(f" {result.offset:#x}: {result.description}")
```
## Compatibility with Binwalk v2
Binwalk3 is designed as a drop-in replacement. Just change your import:
```python
# Old binwalk v2 code
import binwalk
for module in binwalk.scan('file.bin'):
for result in module.results:
print(hex(result.offset), result.description)
# Works exactly the same with binwalk3!
# No code changes needed
```
## API Reference
### `binwalk.scan(*files, **kwargs)`
Main function to scan files for embedded data and signatures.
**Parameters:**
- `*files` (str): One or more file paths to scan
- `signature` (bool): Enable signature scanning (default: True)
- `quiet` (bool): Suppress output (default: True)
- `extract` (bool): Extract identified files
- `directory` (str): Directory for extracted files
- `entropy` (bool): Calculate file entropy
- `matryoshka` (bool): Recursive extraction (like Russian dolls!)
- `verbose` (bool): Enable verbose output
- `threads` (int): Number of threads to use
**Returns:** List of `Module` objects
### Classes
**`Module`**: Contains results for a single file
- `file`: Path to scanned file
- `results`: List of `Result` objects
- `errors`: List of error messages
**`Result`**: A single scan result
- `offset`: Byte offset where match was found
- `description`: Description of what was found
- `size`: Size of identified data (if known)
- `entropy`: Entropy value (if calculated)
- `file`: Source file path
**`Modules`**: Advanced interface for scanning
- `execute(*files, **kwargs)`: Scan files with options
## Performance
Binwalk v3 is significantly faster than v2:
| Operation | v2 Time | v3 Time | Speedup |
|-----------|---------|---------|---------|
| Signature Scan (100MB) | 45s | 12s | 3.75x |
| Extraction (50MB) | 60s | 18s | 3.33x |
| Entropy Analysis | 30s | 8s | 3.75x |
*Benchmarks on Windows 10, Intel i7, SSD*
## Troubleshooting
### "Binary not available" error
If you see this error, the binwalk v3 binary couldn't be found.
**On Windows:** The binary should be bundled. Try reinstalling:
```bash
pip uninstall binwalk3
pip install --no-cache-dir binwalk3
```
**On Linux/Mac:** Install binwalk v3 separately:
```bash
cargo install binwalk
```
Or build from source: https://github.com/ReFirmLabs/binwalk
### No results found
If scanning returns no results, the file might not contain recognized signatures. Try:
- Enabling verbose mode: `scan('file.bin', verbose=True)`
- Checking if file exists and is readable
- Trying with binwalk v3 directly to verify
### Extraction fails on Windows
On Windows, extraction may fail with "privilege error" due to symlink limitations.
**Solutions:**
1. **Run as Administrator**: Right-click Python and select "Run as administrator"
2. **Enable Developer Mode**: Settings → Update & Security → For developers → Developer Mode (grants symlink privileges)
3. **Use WSL/Linux**: For complex extraction workflows
**Note:** Signature scanning works perfectly without admin rights. This only affects extraction.
## Project Links
- **GitHub**: https://github.com/zacharyflint/binwalk3
- **PyPI**: https://pypi.org/project/binwalk3/
- **Issues**: https://github.com/zacharyflint/binwalk3/issues
- **Changelog**: https://github.com/zacharyflint/binwalk3/blob/main/CHANGELOG.md
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Credits
- **Binwalk v3**: https://github.com/ReFirmLabs/binwalk - The amazing Rust rewrite
- **Original Binwalk**: Created by Craig Heffner
- **This Package**: Compatibility layer by Zachary Flint
## Acknowledgments
This package wraps the excellent binwalk v3 project, bringing its performance improvements to the existing v2 Python ecosystem. All credit for the core functionality goes to the binwalk v3 team!
Raw data
{
"_id": null,
"home_page": null,
"name": "binwalk3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "binwalk, firmware, analysis, reverse-engineering, security, binary-analysis, embedded, iot",
"author": null,
"author_email": "Zachary Flint <zach.flint2@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f4/69/76aebb76a4ae77f406d37708742596545301cac6340b65c6531d50fa6950/binwalk3-3.1.3.tar.gz",
"platform": null,
"description": "# Binwalk v3 - Fast Firmware Analysis with v2 API Compatibility\r\n\r\n[](https://badge.fury.io/py/binwalk3)\r\n[](https://pypi.org/project/binwalk3/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA Python package that provides binwalk v2's familiar API while using the blazing-fast binwalk v3 Rust binary under the hood. Get 2-5x faster firmware analysis with zero code changes!\r\n\r\n## Features\r\n\r\n\u2728 **Drop-in Replacement**: Same API as binwalk v2 - just change your import!\r\n\u26a1 **2-5x Faster**: Powered by binwalk v3's Rust implementation\r\n\ud83c\udfaf **Fewer False Positives**: 60-80% reduction in false matches\r\n\ud83e\ude9f **Windows Support**: Bundled Windows x64 binary (no separate installation)\r\n\ud83d\udc0d **Python 3.8+**: Modern Python with type hints\r\n\ud83d\udce6 **Zero Runtime Dependencies**: Pure Python package\r\n\r\n## Installation\r\n\r\n```bash\r\npip install binwalk3\r\n```\r\n\r\nThat's it! The Windows binary is included. On other platforms, install binwalk v3 separately or it will use your system binwalk.\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport binwalk\r\n\r\n# Scan a firmware file\r\nfor module in binwalk.scan('firmware.bin'):\r\n for result in module:\r\n print(f\"Found {result.description} at {result.offset:#x}\")\r\n```\r\n\r\n### Extract Files\r\n\r\n```python\r\nimport binwalk\r\n\r\n# Extract embedded files\r\nbinwalk.scan('firmware.bin', extract=True)\r\n```\r\n\r\n### Entropy Analysis\r\n\r\n```python\r\nimport binwalk\r\n\r\n# Analyze entropy\r\nresults = binwalk.scan('firmware.bin', entropy=True)\r\n```\r\n\r\n### Using the Modules Class\r\n\r\n```python\r\nfrom binwalk import Modules\r\n\r\n# Advanced usage with Modules class\r\nmodules = Modules()\r\nresults = modules.execute('firmware.bin', extract=True, matryoshka=True)\r\n\r\nfor module in results:\r\n print(f\"Scanned: {module.file}\")\r\n print(f\"Found {len(module.results)} results\")\r\n for result in module:\r\n print(f\" {result.offset:#x}: {result.description}\")\r\n```\r\n\r\n## Compatibility with Binwalk v2\r\n\r\nBinwalk3 is designed as a drop-in replacement. Just change your import:\r\n\r\n```python\r\n# Old binwalk v2 code\r\nimport binwalk\r\nfor module in binwalk.scan('file.bin'):\r\n for result in module.results:\r\n print(hex(result.offset), result.description)\r\n\r\n# Works exactly the same with binwalk3!\r\n# No code changes needed\r\n```\r\n\r\n## API Reference\r\n\r\n### `binwalk.scan(*files, **kwargs)`\r\n\r\nMain function to scan files for embedded data and signatures.\r\n\r\n**Parameters:**\r\n- `*files` (str): One or more file paths to scan\r\n- `signature` (bool): Enable signature scanning (default: True)\r\n- `quiet` (bool): Suppress output (default: True)\r\n- `extract` (bool): Extract identified files\r\n- `directory` (str): Directory for extracted files\r\n- `entropy` (bool): Calculate file entropy\r\n- `matryoshka` (bool): Recursive extraction (like Russian dolls!)\r\n- `verbose` (bool): Enable verbose output\r\n- `threads` (int): Number of threads to use\r\n\r\n**Returns:** List of `Module` objects\r\n\r\n### Classes\r\n\r\n**`Module`**: Contains results for a single file\r\n- `file`: Path to scanned file\r\n- `results`: List of `Result` objects\r\n- `errors`: List of error messages\r\n\r\n**`Result`**: A single scan result\r\n- `offset`: Byte offset where match was found\r\n- `description`: Description of what was found\r\n- `size`: Size of identified data (if known)\r\n- `entropy`: Entropy value (if calculated)\r\n- `file`: Source file path\r\n\r\n**`Modules`**: Advanced interface for scanning\r\n- `execute(*files, **kwargs)`: Scan files with options\r\n\r\n## Performance\r\n\r\nBinwalk v3 is significantly faster than v2:\r\n\r\n| Operation | v2 Time | v3 Time | Speedup |\r\n|-----------|---------|---------|---------|\r\n| Signature Scan (100MB) | 45s | 12s | 3.75x |\r\n| Extraction (50MB) | 60s | 18s | 3.33x |\r\n| Entropy Analysis | 30s | 8s | 3.75x |\r\n\r\n*Benchmarks on Windows 10, Intel i7, SSD*\r\n\r\n## Troubleshooting\r\n\r\n### \"Binary not available\" error\r\n\r\nIf you see this error, the binwalk v3 binary couldn't be found.\r\n\r\n**On Windows:** The binary should be bundled. Try reinstalling:\r\n```bash\r\npip uninstall binwalk3\r\npip install --no-cache-dir binwalk3\r\n```\r\n\r\n**On Linux/Mac:** Install binwalk v3 separately:\r\n```bash\r\ncargo install binwalk\r\n```\r\n\r\nOr build from source: https://github.com/ReFirmLabs/binwalk\r\n\r\n### No results found\r\n\r\nIf scanning returns no results, the file might not contain recognized signatures. Try:\r\n- Enabling verbose mode: `scan('file.bin', verbose=True)`\r\n- Checking if file exists and is readable\r\n- Trying with binwalk v3 directly to verify\r\n\r\n### Extraction fails on Windows\r\n\r\nOn Windows, extraction may fail with \"privilege error\" due to symlink limitations.\r\n\r\n**Solutions:**\r\n1. **Run as Administrator**: Right-click Python and select \"Run as administrator\"\r\n2. **Enable Developer Mode**: Settings \u2192 Update & Security \u2192 For developers \u2192 Developer Mode (grants symlink privileges)\r\n3. **Use WSL/Linux**: For complex extraction workflows\r\n\r\n**Note:** Signature scanning works perfectly without admin rights. This only affects extraction.\r\n\r\n## Project Links\r\n\r\n- **GitHub**: https://github.com/zacharyflint/binwalk3\r\n- **PyPI**: https://pypi.org/project/binwalk3/\r\n- **Issues**: https://github.com/zacharyflint/binwalk3/issues\r\n- **Changelog**: https://github.com/zacharyflint/binwalk3/blob/main/CHANGELOG.md\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes with tests\r\n4. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## Credits\r\n\r\n- **Binwalk v3**: https://github.com/ReFirmLabs/binwalk - The amazing Rust rewrite\r\n- **Original Binwalk**: Created by Craig Heffner\r\n- **This Package**: Compatibility layer by Zachary Flint\r\n\r\n## Acknowledgments\r\n\r\nThis package wraps the excellent binwalk v3 project, bringing its performance improvements to the existing v2 Python ecosystem. All credit for the core functionality goes to the binwalk v3 team!\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Binwalk v3 with v2-compatible Python API - Fast firmware analysis",
"version": "3.1.3",
"project_urls": {
"Changelog": "https://github.com/zacharyflint/binwalk3/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/zacharyflint/binwalk3/blob/main/README.md",
"Homepage": "https://github.com/zacharyflint/binwalk3",
"Issues": "https://github.com/zacharyflint/binwalk3/issues",
"Repository": "https://github.com/zacharyflint/binwalk3"
},
"split_keywords": [
"binwalk",
" firmware",
" analysis",
" reverse-engineering",
" security",
" binary-analysis",
" embedded",
" iot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "201126fef4757b956cfff24d62a74bf469c09670fe5419ca7c7929c6682a7bf6",
"md5": "b17200871aa19e9a6f91c368e9a3d694",
"sha256": "859de69540c5af5e25e4251a32e9b977fd921d5e349c202d57e2d8907a50f875"
},
"downloads": -1,
"filename": "binwalk3-3.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b17200871aa19e9a6f91c368e9a3d694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3607255,
"upload_time": "2025-10-20T01:11:21",
"upload_time_iso_8601": "2025-10-20T01:11:21.582644Z",
"url": "https://files.pythonhosted.org/packages/20/11/26fef4757b956cfff24d62a74bf469c09670fe5419ca7c7929c6682a7bf6/binwalk3-3.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f46976aebb76a4ae77f406d37708742596545301cac6340b65c6531d50fa6950",
"md5": "4941d0f9c80bca928afe64e645b40dcc",
"sha256": "468d479101a0e8106eda79b921fa568aef17112082408fd73acbd62dea289d02"
},
"downloads": -1,
"filename": "binwalk3-3.1.3.tar.gz",
"has_sig": false,
"md5_digest": "4941d0f9c80bca928afe64e645b40dcc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3501244,
"upload_time": "2025-10-20T01:11:24",
"upload_time_iso_8601": "2025-10-20T01:11:24.288008Z",
"url": "https://files.pythonhosted.org/packages/f4/69/76aebb76a4ae77f406d37708742596545301cac6340b65c6531d50fa6950/binwalk3-3.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 01:11:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zacharyflint",
"github_project": "binwalk3",
"github_not_found": true,
"lcname": "binwalk3"
}
JSON
