Installing nitropy With pipx

This guide explains how to install nitropy with pipx. pipx creates a virtual environment for nitropy. This means that nitropy and its dependencies don’t conflict with other packages installed on your system.

Note

For Windows users: Windows support is still experimental – please use with caution. You can also use pre-compiled binaries or a MSI installer, see Installing nitropy on Windows.

Installation on Linux

Ubuntu, Debian

You can install nitropy along with all other required dependencies by using:

sudo apt install pipx && pipx ensurepath && pipx install pynitrokey

After logging out or restarting your system, nitropy will now be available.

Arch

You can install nitropy along with all other required dependencies by using:

sudo pacman -S python python-pipx && pipx ensurepath && pipx install pynitrokey

If you have already installed Python on your system, you can simply run:

sudo pacman -S python-pipx && pipx ensurepath && pipx install pynitrokey

After logging out or restarting your system, nitropy will now be available.

Installation on other distributions/operating systems

Preparation

Python 3.9, 3.10 or 3.11

Python is already installed on most macOS and Linux systems or can be downloaded from python.org. See the Downloading Python Guide for more information.

pip

You can install pip with your system package manager or with python3 -m ensurepip. See the pip Installation Guide for more information.

pipx

Before installing nitropy, you have to install and configure pipx:

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

See the pipx Installation Guide for more information.

Note

For Linux Users - currently a transient dependency (oscrypto) is generating issues on some Linux distrubutions. The respective GitHub issue documents the currently needed workaround:

pipx inject --pip-args="--upgrade --force" pynitrokey "oscrypto @ git+https://github.com/wbond/oscrypto.git@1547f535001ba568b239b8797465536759c742a3"

Installation

Now you can install nitropy from the pynitrokey package:

pipx install pynitrokey

nitropy is now available in your path:

nitropy --help

Upgrade

You can upgrade the package with the following command:

pipx upgrade pynitrokey

Troubleshooting

If you encounter problems, please make sure that you use the latest version by comparing the output of nitropy version with the release list on GitHub. If an upgrade does not install the latest version, you might be running into one of the following problems.

Wrong Python Version

nitropy requires Python 3.9 or 3.10. If your default Python installation is older or newer than that and cannot be updated, you have to additionally install Python 3.9 and specify the name of its Python executable when calling pipx, for example:

$ pipx install --python python3.9 pynitrokey

libusb-1.0.dylib not found

When running nitropy on macOS, you might see an error message indicating a missing libusb-1.0.dylib file. This can be fixed by manually installing libusb, e. g. with homebrew:

$ brew install libusb

Usage Notes

All Platforms

If you want to use nitropy with a Nitrokey Pro or Nitrokey Storage device, you also have to install libnitrokey.

Windows

Windows support is still experimental – please use with caution.

You might have to run nitropy with administrator rights to be able to connect to a device.

Linux

On Linux systems, you also need the Nitrokey udev rules. These are shipped with libnitrokey. Alternatively, you can install them manually:

wget https://raw.githubusercontent.com/Nitrokey/nitrokey-udev-rules/refs/heads/main/41-nitrokey.rules
sudo mv 41-nitrokey.rules /etc/udev/rules.d/

See Setting up The udev Rules for more information.

Usage of PIV features

To be able to use the PIV functionality of nitropy (nitropy nk3 piv), you need to install the pyscard dependency too:

pipx install pynitrokey[pcsc]

Next Steps

You can find more information on using nitropy in these guides: