Install & Compatibility
Where this runs
tested against v1.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
vivisect
✓ import vivisect
Primary import for the VivWorkspace and core functionality
vivisect.const
✓ import vivisect.const as v_const
For accessing various constants like location types (LOC_OP, LOC_IMPORT) and xref types (REF_CODE, REF_PTR)
PE
✓ import PE
For direct parsing of Portable Executable (PE) files without a full workspace
Elf
✓ import Elf
For direct parsing of Executable and Linkable Format (ELF) files without a full workspace
This quickstart demonstrates how to initialize a Vivisect workspace, load a binary file, perform auto-analysis, and then programmatically access discovered functions and code locations. It illustrates the fundamental steps for static analysis.
import vivisect
import os
# Create a dummy binary file for demonstration
dummy_bin_path = 'temp_dummy.bin'
with open(dummy_bin_path, 'wb') as f:
f.write(b'\x90\x90\x90\xc3') # NOP NOP NOP RET
try:
# Create a VivWorkspace instance
vw = vivisect.VivWorkspace()
# Load a binary file into the workspace
# Replace 'path/to/your/binary.exe' with a real binary or use the dummy
vw.loadFromFile(dummy_bin_path)
# Perform auto-analysis on the loaded binary
print("Starting analysis...")
vw.analyze()
print("Analysis complete.")
# Example: Get functions discovered by analysis
functions = vw.getFunctions()
print(f"Found {len(functions)} functions:")
for fva in functions:
f_name = vw.getName(fva)
print(f" 0x{fva:x}: {f_name}")
# Example: Get locations (e.g., instructions)
locations = vw.getLocations()
print(f"Found {len(locations)} locations:")
for va, size, ltype, tinfo in locations:
op = vw.getOpcode(va)
print(f" 0x{va:x}: {op.mnem} {op.opers_str}")
finally:
# Clean up the dummy file
if os.path.exists(dummy_bin_path):
os.remove(dummy_bin_path)
vivbin --version
Debug
Known issues
breakingVivisect underwent a significant, backwards-incompatible transition from Python 2 (v0.x.x) to Python 3 (v1.0.0 and above). Old workspaces saved in Python 2's 'basicfile' format are not directly compatible with Python 3 versions.fixUse the conversion script (vivisect.storage.tools.convert) available in vivisect v0.2.1 (Python 2) or v1.0.1+ (Python 3) to migrate old 'basicfile' workspaces to the 'msgpack' format. Example: `python2 -m vivisect.storage.tools.convert <basicfile_workspace>`
affects: <1.0.0 to >=1.0.0
breakingSome API signatures changed during the Python 2 to Python 3 migration, notably for memory read/write operations. Scripts written for older Python 2 versions may require adjustments.fixConsult the Vivisect documentation and migration guide for specific API changes and update your code accordingly.
affects: <1.0.0 to >=1.0.0
gotchaWhen installing Vivisect with GUI support on Ubuntu, installing `PyQt5` via `pip install "vivisect[gui]"` might lead to issues.fixOn Ubuntu, it is often more stable to install `PyQt5` and `PyQtWebkit` using the system package manager first: `sudo apt install python3-pyqt5 python3-pyqt5.qtwebkit`, then install `vivisect` without the `[gui]` extra.
affects: All versions with GUI
Errors
Common errors & fixes
Exception: Address (xxxx) not in maps!
This error typically indicates that Vivisect's analysis tried to access a memory address that is not part of the loaded binary's memory map. This can happen with malformed binaries, incomplete file loading, or issues during auto-analysis.
fixVerify the integrity of the binary file. Ensure the `vw.loadFromFile()` or `vw.loadFromFd()` call is successful before `vw.analyze()`. For unusual binary types, you might need to manually configure memory maps or use a custom loader if the standard parsers (PE, Elf) are insufficient.
Python 2 workspace not loading in Python 3 Vivisect.
Workspaces saved with Python 2 versions of Vivisect (especially using the default 'basicfile' storage, which relies on Python's `pickle`) are not compatible with Python 3 due to fundamental differences in object serialization.
fixBefore upgrading to Python 3 Vivisect, use a Python 2 Vivisect installation (v0.2.1) to convert old workspaces to the `msgpack` format. For example, `python2 -m vivisect.storage.tools.convert <old_workspace.viv> --name <new_workspace.mpviv>`. The `msgpack` format is cross-version compatible.
GUI console not showing typing or interactive shell issues.
When running the Vivisect GUI (`vivbin`) from a console, the interactive Python shell or function emulator can sometimes interfere with terminal settings.
fixIf the command line stops responding or showing input, try typing `stty sane` and pressing Enter (blindly if necessary) to reset the terminal settings. If multiple emulators/CLIs are active, you may need to reset the console state via `Plugins -> Ion -> Reset Console In Use` if using the VivisectION extension.
Upgrade
Version history
1.3.2latest on PyPI · released Mar 31, 2026
Audit
Dependencies
PyQt5optionalRequired for the graphical user interface (GUI) components.