Documentation
Guides
Upgrade & Uninstall

Upgrade & Uninstall

NAT ships two built-in commands for lifecycle management: nat upgrade checks PyPI for updates and optionally installs them, and nat uninstall cleanly removes NAT config, data, and shell completions.

nat upgrade

If nat upgrade isn't recognized, update with pip install --upgrade nat-engine first, then use nat upgrade for future updates.

nat upgrade compares the installed nat-engine version against the latest release on PyPI, then optionally upgrades via pip.

Flags

FlagDescription
--checkCheck if an update is available without installing it
--migrateRun alembic upgrade head after upgrading (for self-hosted deployments with a database)
--preInclude pre-release versions when checking or upgrading

Examples

# Check if an update is available (dry run — nothing is installed)
nat upgrade --check
 
# Upgrade to the latest stable release
nat upgrade
 
# Upgrade and apply database migrations (self-hosted deployments)
nat upgrade --migrate
 
# Upgrade to the latest pre-release
nat upgrade --pre

What it does

Check installed version

Reads the currently installed nat-engine version using importlib.metadata.

Query PyPI

Fetches the latest version from the PyPI JSON API at https://pypi.org/pypi/nat-engine/json.

Compare versions

Prints a summary showing the installed and latest versions:

nat-engine: 1.2.0 → 1.3.0  (upgrade available)

If you used --check, the process stops here without making any changes.

Install the update

Runs pip install --upgrade nat-engine (or pip install --upgrade --pre nat-engine for pre-releases) and prints the new version on completion.

Run database migrations (optional)

If --migrate was passed, runs alembic upgrade head to apply any schema changes included in the new release.

For self-hosted deployments, always run nat upgrade --migrate when upgrading across minor versions to ensure the database schema stays in sync.

nat uninstall

nat uninstall removes NAT configuration files, scan data, and shell completion scripts. It does not automatically run pip uninstall — it prints the command for you to run manually.

Flags

FlagShortDescription
--keep-configPreserve .natrc files in the current directory and ~/.natrc
--yes-ySkip the confirmation prompt
--purgeAlso run alembic downgrade base and remove Docker volumes

Examples

# Interactive uninstall — prompts for confirmation
nat uninstall
 
# Keep .natrc files but remove everything else
nat uninstall --keep-config
 
# Full purge including database tables and Docker volumes, no prompt
nat uninstall --purge --yes

What it removes

ItemPathNotes
Local config file./.natrcSkipped with --keep-config
Global config file~/.natrcSkipped with --keep-config
Data directory~/.nat/Scan data, logs, reports
Bash completion~/.bash_completion.d/natIf installed
Zsh completion~/.zsh/completions/_natIf installed
Fish completion~/.config/fish/completions/nat.fishIf installed

What it does NOT do

nat uninstall does not remove the Python package. After running it, uninstall the package yourself:

pip uninstall nat-engine

--purge — full database and Docker cleanup

--purge is intended for self-hosted deployments and performs two additional steps:

  1. Runs alembic downgrade base to drop all database tables created by NAT
  2. Removes Docker volumes tagged with the nat label
⚠️

--purge permanently deletes all scan history from the database and any Docker volumes. This cannot be undone.

Full walkthrough

Run nat uninstall

nat uninstall

Confirm when prompted

This will remove:
  • .natrc (current directory)
  • ~/.natrc
  • ~/.nat/ data directory
  • Shell completion files

Continue? [y/N]

Use --yes / -y to skip this prompt in scripts.

Review the removal summary

NAT prints each item as it is removed:

✓ Removed .natrc
✓ Removed ~/.natrc
✓ Removed ~/.nat/
✓ Removed shell completions

To fully remove NAT, run:
  pip uninstall nat-engine

Uninstall the Python package

pip uninstall nat-engine

Next steps

Was this helpful?
CLI ReferenceEnvironment Doctor