Getting started¶
Requirements¶
banip supports macOS, Linux, and native Windows, including use from PowerShell. Windows Subsystem for Linux (WSL) is also an option; it is not required to install or run banip. Python 3.12 or newer is required. The recommended installer, uv, can download and manage a compatible Python version automatically. The pipx and pip installation methods require a compatible Python installation.
Installing and running banip does not require uv. It is required only for banip development.
After installation, downloading GeoLite2 Country CSV data requires a free or paid MaxMind account. The ipsum feed does not require MaxMind credentials.
Install banip¶
Install banip as an isolated command-line application. This avoids dependency conflicts with other Python applications and protects operating-system-managed Python environments. Do not install banip globally into the system Python environment.
uv (recommended)¶
uv installs banip in an isolated environment and supplies a managed Python version:
Upgrade an existing installation with:
If uv reports that its executable directory is not on PATH, run
uv tool update-shell and open a new terminal.
See the uv tool documentation for installation and environment-management details.
pipx¶
pipx also installs command-line
applications into isolated environments. Install pipx, make its
application directory available on PATH, and install banip using
Python 3.12 or newer:
Open a new terminal after pipx ensurepath if it changed your shell
configuration. If pipx cannot locate Python 3.12, pass the full path to
a compatible Python executable with --python.
Upgrade an existing installation with:
See the pipx installation guide for platform-specific setup.
pip in a virtual environment¶
For manual environment management, create a dedicated virtual environment with Python 3.12 or newer, activate it, and install banip:
python3.12 -m venv ~/.local/share/banip-venv
source ~/.local/share/banip-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install banip
Activate this environment before running or upgrading banip in a new terminal. Upgrade banip with:
See the Python Packaging User Guide for more information about pip and virtual environments.
Windows PowerShell¶
With Python 3.12 installed and available through the Python launcher, create an environment and invoke its Python directly:
$banip_venv = Join-Path $env:LOCALAPPDATA 'banip-venv'
py -3.12 -m venv $banip_venv
& "$banip_venv\Scripts\python.exe" -m pip install --upgrade pip
& "$banip_venv\Scripts\python.exe" -m pip install banip
& "$banip_venv\Scripts\banip.exe" --version
Activation is optional. Continue invoking Scripts\banip.exe directly,
or activate with & "$banip_venv\Scripts\Activate.ps1" when your
PowerShell execution policy permits it. Upgrade with:
Verify the installation¶
For any installation method, confirm that the command is available:
Initialize local data¶
Create the local directory structure and starter configuration:
This writes ~/.banip/banip.yaml and creates the local data
directories. If the prior flat configuration files exist,
initialization imports their non-comment entries into the new YAML
configuration without deleting the source files. Invalid IP entries
retain the legacy behavior and are ignored. If an existing targets.txt
contains no valid country codes, initialization stops without writing
banip.yaml; select at least one country or remove the legacy file to
use the starter policies.
On native Windows, ~/.banip is the .banip directory under your user
profile, normally C:\Users\<username>\.banip. Use UTF-8 for edited
configuration and input files. LF and CRLF input line endings are
accepted; generated lists use LF for portability to proxy and firewall
systems. banip generates files rather than configuring the Windows
firewall.
For UTF-8 logs or pipelines on Windows, set Python's output encoding for the current PowerShell session:
The receiving program must decode that output as UTF-8 too. Without this setting, redirected Python output can use the Windows code page, which can display replacement characters in a UTF-8 log viewer. Rich may use ASCII table borders in Windows CI or legacy terminals; this is an intentional rendering fallback.
Running banip database init --overwrite replaces an existing YAML
file with the documented starter configuration. It does not reimport
retained legacy files.
Download source data¶
Download the ipsum feed:
Set MaxMind credentials in the environment or in the dotenv-style file
named by database.secrets_file in banip.yaml:
To set credentials for the current PowerShell session instead:
In YAML, use forward slashes or single quotes for Windows paths, such
as secrets_file: 'C:\Users\Example User\.secrets'. Quote command-line
paths containing spaces too, for example
banip build --outfile 'C:\Users\Example User\blocklist.txt'.
Then download the GeoLite2 Country CSV files:
Run banip database update to refresh both sources.
Build your first blocklist¶
Review the example restricted and public country policies in
banip.yaml, adjust their country codes, then run:
The build writes:
~/.banip/ip_blocklist.txt
~/.banip/ip_allowlist.txt
~/.banip/country_allowlist_restricted.txt
~/.banip/country_allowlist_public.txt
~/.banip/haproxy_geo_ip.txt
Additional named country policies produce corresponding
country_allowlist_<policy>.txt files.
See Configuration for the available settings and Commands for build options. Existing 2.x installations should review Upgrading to 3.0.