Installing nb: macOS, Linux, Windows, and Other Platforms

nb is a single portable Bash script with minimal requirements. You can install it through a package manager for the most convenient experience, or download it directly when a package manager is not available. On every platform the result is the same: one executable, ready to run.

Dependencies

Required

Before installing nb, make sure the following are available on your system:

Bash — nb is a Bash script. It works perfectly with Zsh, Fish, and any other shell as your primary login shell; the system just needs Bash available.
Git — used for automatic versioning and sync.
A text editor with command-line support, such as Vim, Emacs, Visual Studio Code, Sublime Text, Helix, micro, nano, or any other editor you prefer.

Optional

nb checks the environment for additional tools and uses them to enhance the experience whenever they are available. None of these are required for core functionality. Recommended optional dependencies:

Tool	What it enables
`bat`	Syntax-highlighted note previews
`ncat` or `socat`	Local web browsing interface (`nb browse`)
`pandoc`	Format conversion, Markdown rendering of bookmarked pages
`rg` (ripgrep)	Faster full-text search
`tig`	Visual Git history browsing
`w3m`	Terminal web browser for `nb browse`

On Ubuntu and WSL, run sudo nb env install after installing nb to automatically install the recommended optional dependencies.

Also supported for various enhancements: Ack, afplay, asciidoctor, The Silver Searcher (ag), catimg, Chafa, Chromium/Chrome, eza, ffplay, ImageMagick, glow, GnuPG, highlight, imgcat, joshuto, kitty’s icat kitten, lowdown, lsd, Links, Lynx, mdcat, mdless, mdv, Midnight Commander (mc), mpg123, MPlayer, netcat, pdftotext, Pygments, Ranger, readability-cli, rga/ripgrep-all, sc-im, termvisage, termpdf.py, Tidy-Viewer (tv), timg, vifm, viu, VisiData.

Installation Methods

Installing via Homebrew is the recommended method on macOS. It automatically installs the recommended optional dependencies and sets up tab completion for Bash, Zsh, and Fish.

brew install xwmx/taps/nb

nb is also available in homebrew-core. Installing it alongside the bash formula is recommended:

brew install nb bash

To install the latest development version directly from the repository:

brew install xwmx/taps/nb --head

Install via npm on Ubuntu, Windows (WSL/MSYS/Cygwin), and anywhere Node.js is available:

npm install -g nb.sh

After installation completes, install the completion scripts:

sudo "$(which nb)" completions install

On Ubuntu and WSL, also install the optional dependencies:

sudo "$(which nb)" env install

On Windows, socat (MSYS or Cygwin) is recommended for the nb browse web interface.

nb is also available under its original package name notes.sh, which includes an extra notes executable wrapping nb.

Download and install nb directly using curl or wget. These one-liners install nb to /usr/local/bin and set up tab completion:

# Install using curl
sudo curl -L https://raw.github.com/xwmx/nb/master/nb -o /usr/local/bin/nb &&
  sudo chmod +x /usr/local/bin/nb &&
  sudo nb completions install --download

# Install using wget
sudo wget https://raw.github.com/xwmx/nb/master/nb -O /usr/local/bin/nb &&
  sudo chmod +x /usr/local/bin/nb &&
  sudo nb completions install --download

User-only installation (no sudo required) — add nb to any directory on your $PATH, for example ~/bin:

# Download with curl
curl -L https://raw.github.com/xwmx/nb/master/nb -o ~/bin/nb && chmod +x ~/bin/nb

# Download with wget
wget https://raw.github.com/xwmx/nb/master/nb -O ~/bin/nb && chmod +x ~/bin/nb

If you later gain sudo access and want to install completions and optional dependencies:

sudo nb env install

Install from source using Make:

Clone the repository

git clone https://github.com/xwmx/nb.git

Navigate to the repository root

cd nb

Run the install target

sudo make install

This installs tab completion scripts on all systems and the recommended optional dependencies on Ubuntu and WSL.

Install with bpkg, the Bash package manager:

bpkg install xwmx/nb

Install with basher:

basher install xwmx/nb

Tab Completion

Bash, Fish, and Zsh tab completion is enabled automatically when nb is installed via Homebrew, npm (with the completions install step), make, or the curl/wget commands shown above. If completion is not working after installation, run:

sudo nb completions install

Or install both completions and optional dependencies together:

sudo nb env install

For manual setup instructions, see the completion installation guide.

Updating

Package manager (Homebrew / npm)
nb update (all other methods)

Use the package manager’s standard upgrade command:

# Homebrew
brew upgrade nb

# npm
npm update -g nb.sh

When nb was installed via curl, wget, make, bpkg, or basher, update to the latest version with the built-in update command:

nb update

Getting Started

Core Features

Organization

Data & Sync

Customization

Installing nb: macOS, Linux, Windows, and Other Platforms

Dependencies

Required

Optional

Installation Methods

Tab Completion

Updating

Build docs developers (and LLMs) love

Getting Started

Core Features

Organization

Data & Sync

Customization

Documentation Index

​Dependencies

​Required

​Optional

​Installation Methods

​Tab Completion

​Updating

Build docs developers (and LLMs) love

Dependencies

Required

Optional

Installation Methods

Tab Completion

Updating