Troubleshooting — AuditWalk

Install

auditwalk: command not found after install

When you install with python3 -m pip install --user, the auditwalk command is placed in ~/.local/bin/. If your shell does not include that directory in its PATH, the command will not be found even though the install succeeded.

Step 1 — Confirm the file is there:

Check install location

ls ~/.local/bin/auditwalk

If the file exists, the install worked — the problem is PATH. If the file is missing, the install did not complete — re-run the install command from the Downloads page.

Step 2 — Add ~/.local/bin to your PATH. Run the command for your shell, then open a new terminal tab:

bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Step 3 — Confirm it works:

auditwalk --version

Install

Installation fails

If python3 -m pip install --user auditwalk-0.1.3-py3-none-any.whl fails, work through these cases in order.

Python is installed but pip is missing. Some Linux distributions ship Python without pip. Install it using your package manager:

Debian / Ubuntu

sudo apt install python3-pip

Fedora / RHEL / CentOS

sudo dnf install python3-pip

Arch

sudo pacman -S python-pip

After installing pip, re-run the install command from the Downloads page.

Externally managed Python environment error. Some newer Linux distributions protect the system Python environment and may block pip installs with this message:

Error text

error: externally-managed-environment

This protection exists to prevent pip from conflicting with your operating system's package manager. For AuditWalk's user-account install, you may use the command below as a fallback. Do not combine it with sudo.

python3 -m pip install --user --break-system-packages auditwalk-0.1.3-py3-none-any.whl

Architecture mismatch. AuditWalk requires x86_64 (amd64). Confirm your system architecture:

uname -m

ARM builds are not yet available. If you need ARM support, contact support.

Do not use sudo pip. Running sudo python3 -m pip install installs into the system Python and can conflict with OS-managed packages. Use --user instead. Only use sudo if the troubleshooting guide specifically instructs it for your situation.

Permissions

Permission denied during scan

AuditWalk requires read access to the paths it scans. Permission errors mean the process user cannot read a directory or file in the scan scope.

Option 1 — Run with elevated privileges (if your security policy allows it):

sudo auditwalk scan

Option 2 — Run the standard scan as your current user and review the specific path that failed:

auditwalk scan

Option 3 — Identify the failing path. The output includes the path that triggered the permission error. Verify ownership:

ls -la /path/that/failed

Note: System directories like /proc, /sys, and /dev are excluded from default scan scope. Permission errors on these paths indicate a non-default configuration.

Baseline

Baseline scan won't initialize

If baseline setup exits without producing a baseline, work through these steps.

1. Confirm the CLI can produce a scan artifact first.

auditwalk scan
auditwalk status

2. Check the data directory is writable:

ls -la ~/.local/share/auditwalk/

If it doesn't exist or isn't writable, create it:

mkdir -p ~/.local/share/auditwalk && chmod 700 ~/.local/share/auditwalk

3. Check available disk space:

df -h ~/.local/share/auditwalk/

Compare

Compare reports unexpected or excessive drift

If compare returns far more changes than expected, the most common causes are:

A system update ran since baseline. This is expected — AuditWalk is accurately reporting what changed. Review the output, confirm the update was intentional, and re-baseline:

auditwalk compare <baseline_id>
auditwalk doctor

The compare command is using the wrong baseline. Verify the available trust state:

auditwalk status

Volatile paths are in scope. Directories like /tmp, /var/log, and /run change constantly. Exclude them:

auditwalk scan --profile forensic_local

Important: If drift output contains paths you don't recognize, do not re-baseline without reviewing. Unexpected drift is the signal the tool is designed to surface.

Licensing

License key activation error

If your license key is not activating, work through the following.

1. Confirm the key is complete. License keys include hyphens and are case-sensitive. Copy directly from your order confirmation email — do not retype.

2. Check network connectivity. License activation requires an outbound connection:

curl -I https://auditwalk.com

3. Confirm local license status. This shows whether the CLI currently sees an active license:

auditwalk license status

If the key has already reached its device limit, contact support with your order ID so we can help reset access.

4. If the error persists, email help@auditwalk.com with your order ID and the exact error message from the CLI.

Licensing

Confirm license status after activation

If activation appears to work but you are not sure AuditWalk sees the license, verify the local status.

1. Run the status command:

auditwalk license status

The output should show your plan and activation state. A missing license prints Free/no license activated.

2. Confirm general tool status:

auditwalk status

3. If the status is wrong, re-run activation with the exact key from your email:

auditwalk license activate YOUR_LICENSE_KEY

Support

Still stuck

If none of the above resolved your issue, contact support. Include the following for the fastest response:

Operating system and distribution (e.g. Ubuntu 24.04, Fedora 40)
AuditWalk version: auditwalk --version
The exact command you ran
The complete error output (copy/paste, not a screenshot)
Your order ID if the issue is related to licensing

Support email

help@auditwalk.com

You can also browse FAQ and CLI Reference for additional context before reaching out.