Skip to main content
Version: 0.19.0

Host Software Installation

The CrackNuts host software provides a Python-based development SDK. The default integrated development environment is Jupyter, which includes built-in components for convenient device control and data acquisition. Users can also control the devices using standard Python scripts outside the Jupyter environment.

Using this SDK requires basic Python programming knowledge. If you are not yet familiar with Python, it is recommended to refer to Liao Xuefeng's Python tutorial for learning.

CrackNuts host software, as a Python library, supports direct installation via pip, or you can use our provided quick installation script for configuration. The quick installation script will automatically create a Conda virtual environment and install CrackNuts and its related dependencies.

You can choose any of the following methods for installation according to your needs.

Quick Command Installation​

When your computer has no Python environment or any Python virtual environment installed, it is recommended to use the quick installation method. After installation, the following actions will be performed:

  1. Install Miniconda (if already present in the system, the existing version will be used)
  2. Create a virtual environment named cracknuts with Python version 12.3
  3. Install CrackNuts dependencies (latest stable version)
  4. Create two desktop shortcuts: CrackNuts and CrackNuts Tutorials, for easy access to the virtual environment or opening tutorials.

Currently, the quick installation script supports Windows and Linux systems. Support for MacOS will be added in future versions.

tip

Users in China can choose the recommended script for domestic network to install, which uses domestic servers for downloading installation files and automatically configures conda and pip mirrors in China to speed up the installation process.

curl https://raw.githubusercontent.com/cracknuts-team/cracknuts/refs/heads/main/install/win-install.ps1 -o "cracknuts-win-install.ps1"; powershell -ExecutionPolicy Bypass -File ".\cracknuts-win-install.ps1"; del "cracknuts-win-install.ps1"

Recommended script for domestic network:

curl https://gitee.com/cracknuts-team/cracknuts/raw/main/install/install.ps1 -o "cracknuts-win-install.ps1"; powershell -ExecutionPolicy Bypass -File ".\cracknuts-win-install.ps1" -EnableChinaConfig; del "cracknuts-win-install.ps1"

After successful installation on Windows, two shortcuts will appear on the desktop:

alt text

Double-click the CrackNuts shortcut or click the CrackNuts icon in the Start menu to open the Conda virtual environment for CrackNuts. You can then start using CrackNuts for device control and data acquisition.

cracknuts_env

Double-click the CrackNuts Tutorials shortcut or click the CrackNuts Tutorials icon in the Start menu to open the tutorial directory with Jupyter. You can then select and learn from the chapters that interest you.

tutorials

PIP Installation​

If you are familiar with Python and virtual environment configuration, you can also install via pip. When installing with pip, it is recommended to create a virtual environment to avoid affecting your system's Python environment.

Requirements​

If you need to install CrackNuts into an existing Python environment, or use CrackNuts within a Jupyter environment, please ensure your environment meets the following requirements:

  • Python version 3.12.5 or higher (check with python --version; Linux and MacOS users in non-virtual environments need to run python3 --version), or use virtual environment tools like Conda or uv that can manage Python versions.

  • If using Jupyter for development and need to use CrackNuts in an existing environment, ensure that Jupyter is installed with the following versions or higher (verify with jupyter --version).

IPython          : 8.28.0
ipykernel        : 6.29.5
ipywidgets       : 8.1.5
jupyter_client   : 8.6.3
jupyter_core     : 5.7.2
jupyter_server   : 2.14.2
jupyterlab       : 4.2.5
nbclient         : 0.10.0
nbconvert        : 7.16.4
nbformat         : 5.10.4
notebook         : 7.2.2
traitlets        : 5.14.3

For more information on virtual environments, visit Python Virtual Environments or refer to Tips and Tricks - Python Virtual Environment for configuration.

Installation​

In domestic environments, configure domestic mirrors to speed up dependency installation. Refer to Tips and Tricks - PIP Mirror Configuration for setup.

Execute the following command in the command line to install:

pip install cracknuts[jupyter]

如果您是在已有的Jupyter的环境中进行安装，可仅安装核心库：

pip install cracknuts

After successful installation, execute cracknuts welcome to view the welcome message.

Update​

After successfully installing via either of the above methods, enter the CrackNuts environment and execute the following command to update. If the configured mirror in the domestic environment does not have the latest version of CrackNuts, you can specify the pypi repository for the update.

pip install -U cracknuts[jupyter]