Installation

Install and run hns. This guide covers how to install hns, configure it, and upgrade to the latest version.

Prerequisites

hns is a Python application. While uv and pipx manage Python installations within isolated environments, having a system Python (3.10+) available is recommended.

Run Without Installing

For a quick trial or infrequent use, you can run hns directly without a permanent installation using uvx. If you have uv installed, uvx comes bundled with it.

uvx hns

This will run hns using a temporary, isolated virtual environment. All of the usual hns commands and features will work with uvx hns.

Installation

We recommend installing hns with uv for the best performance. pipx is also an excellent choice.

uv (Recommended)

uv is an extremely fast Python package and project manager, written in Rust.

Install hns with uv

uv tool install hns

Installing uv: If you don't have uv installed yet, you can install it with the following commands. Check the detailed instructions in the uv installation guide.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pipx

pipx is a tool to install and run Python applications in isolated environments.

Install hns with pipx

pipx install hns

Installing pipx: If you don't have pipx installed yet, use the commands below to install it based on your operating system. See the pipx installation guide for more details.

macOS (Homebrew)

brew install pipx
pipx ensurepath

Linux / Windows

python3 -m pip install --user pipx
python3 -m pipx ensurepath

pip

Managing Python Environments

Using pip to install applications directly can lead to dependency conflicts. We strongly recommend using a virtual environment to isolate hns. uv and pipx handle this for you automatically.

Recommended pip method: Virtual Environment

This is the safest way to install hns with pip.

1. Create and activate a virtual environment

python -m venv ~/.venvs/hns
source ~/.venvs/hns/bin/activate  # On Windows: ~/.venvs/hns/Scripts/activate

2. Install hns inside the environment

pip install hns

To use hns, you must first activate the environment: source ~/.venvs/hns/bin/activate.

Alternative: User-level Install

If you prefer not to manage a virtual environment, you can install hns to your user directory. This is less isolated and may still cause conflicts.

Install hns with pip --user

pip install --user hns

You must ensure the user scripts directory (e.g., ~/.local/bin) is in your PATH.

First Run

The first time you transcribe with hns, it will download the configured Whisper model. This requires an internet connection. Subsequent transcriptions using the same model are fully offline.

Post-Installation: Quick Configuration (Optional)

You can control the transcription model and language using environment variables.

• Model Selection: Override the default base model.

  export HNS_WHISPER_MODEL="small" # Options: tiny, base, small, medium, large-v3, etc.

• Language: Force a specific language instead of auto-detecting.

  export HNS_LANG="ja" # ISO 639-1 code

For detailed instructions, including how to set these variables permanently, see the Configuration guide.

Upgrading to the Latest Version

Keep hns up-to-date to get the latest features and bug fixes.

How was hns installed?

If you don't remember the installation method, these commands can help you find out.

Check for uv

uv tool list | grep hns

Check for pipx

pipx list | grep hns

Check for pip

pip show hns

Upgrade Commands

Once you know the method, use the corresponding command to upgrade.

uv

uv tool upgrade hns

pipx

pipx upgrade hns

pip

pip install --upgrade --user hns

uvx

uvx does not require upgrading. It automatically fetches the latest version of hns every time it runs. To use a specific version, you can pin it: uvx hns@1.0.1.

Verification

To confirm hns is installed and working correctly, run:

hns --version
hns --list-models

---

Now that hns is installed, you're ready to start transcribing! Check out the Quick Start guide to make your first transcription. After that, explore the use cases to integrate hns into your workflows.