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

Arm Not Supported#

Currently, recent nitropy versions cannot be installed on Arm platforms due to a dependency issue (GitHub issue). As a workaround, you can use an x86 Python installation in a Rosetta terminal as described in this discussion).

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: