Getting Started

Example Jupyter notebooks

Here, we provide Jupyter notebooks for a variety of examples that can be downloaded for interactive use.

Analysis examples

Analyze the equilibrium base-pairing properties one or more test tube ensembles (or one or more complex ensembles) — these are the all-purpose sequence analysis tools.

Design examples

Design the the sequences for one or more test tube ensembles (or one or more complex ensembles) — these are the all-purpose sequence design tools.

Sample \LaTeX files are provided for the multi-tube design specifications to assist with making new design specs in a standardized format.

Utilities examples

Analyze or design a single complex ensemble — these are quick tools applicable when your ensemble is a single complex.


Note that each Jupyter notebook starts by loading the NUPACK Python module:

from nupack import *

Installation requirements

NUPACK 4 is a C++ library distributed as a Python package. The following Python packages are required:

  • Python 3.7-3.11
  • numpy
  • scipy
  • pandas

The following packages are recommended to facilitate interactive usage:

  • matplotlib
  • jupyterlab

NUPACK 4 Python packages can be installed for Mac/Linux operating systems or on the Linux subsystem of Windows 10/11. Alternatively, NUPACK may be compiled from source on Mac/Linux.

An easy way to install all of these dependencies is by installing Anaconda.

Mac/Linux installation


Note that for new Macs using an M1 or M2 (arm64) architecture, you must make sure to use a native Python distribution. Separate downloads for the Anaconda or miniconda distributions are available – make sure to choose the distributions labeled “M1”. Importing NUPACK will only function correctly using a native Python distribution. You may use the command

python3 -c "import platform; print(platform.machine())"
to see your installed architecture; this should be arm64 when using an M-series Mac.

  1. Verify your Python installation (make sure you have Python 3.6 or newer):

    python3 --version

    If this command does not run, troubleshoot your Python installation. You may not have your $PATH environment variable set correctly.

  2. Update your installation of pip and install the optional dependencies. Run the following commands

    python3 -m pip install -U pip
    python3 -m pip install -U matplotlib jupyterlab

    Alternatively, if you are using Anaconda, replace the above commands with:

    conda install --update-all pip matplotlib jupyterlab

    If this command does not run, troubleshoot your Anaconda installation. You may not have your $PATH environment variable set correctly.

  3. After agreeing to the NUPACK license, download the NUPACK package (e.g., nupack-4.0.0) into your Downloads folder and make sure it is unzipped.

  4. Install the NUPACK 4 Python module by running the following command in your terminal (type y when prompted):

    python3 -m pip install -U nupack -f ~/Downloads/nupack-VERSION/package

    Make sure to replace nupack-VERSION with the correct folder name (e.g., nupack-4.0.0).

  5. Check that the correct nupack version is now installed by running the following commmand:

    python3 -m pip show nupack

    If the version is not correct, go back to Step 4, double-check the folder name, and rerun the command.

  6. Validate your NUPACK 4 installation by running the following commands:

    python3 -m pip install -U pytest
    python3 -m pytest -v --pyargs nupack
  7. You can now conveniently run NUPACK 4 jobs as Jupyter notebooks (see above for example notebooks). You can launch a web-based Jupyter notebook browser from the command line:

    jupyter lab

    and browse to open your notebook of choice. Click Run->Run All Cells to run the entire notebook. If no browser window appears, try navigating to the displayed link in your terminal. If this doesn’t work, troubleshoot your Jupyter installation.

Windows installation

NUPACK may be installed on Windows 10/11 using the Windows Subsystem for Linux 2 (WSL2).

  1. Click the start menu and search for “Windows Features”. Click on “Turn Windows features on or off”. Check the “Windows Subsystem for Linux” icon

Windows features

  1. Download Ubuntu from the Microsoft Store

Windows store

  1. Open the Ubuntu app and set a username and password

    Ubuntu setup

  2. (Optional) Open the properties window and enable copy paste

Ubuntu properties

  1. Install NUPACK as if using Linux using the following commands (type y when prompted):
mkdir nupack-latest
cd nupack-latest
cp /mnt/c/Users/YOUR-USERNAME/Downloads/ ./
sudo apt install unzip
cd ..

/bin/bash -b
miniconda3/bin/conda update -n base -c defaults conda

export PATH=$HOME/miniconda3/bin:$PATH
echo 'export PATH=$HOME/miniconda3/bin:$PATH' >> ~/.bashrc

conda install numpy scipy pip matplotlib pandas jupyterlab
pip install -U nupack -f ./nupack-VERSION/package

jupyter lab

Make sure to replace /YOUR-USERNAME/Downloads above with the appropriate directory and nupack-VERSION with the correct version (e.g., nupack-4.0.0).

  1. Use your web browser to open localhost:8888 and use Jupyter Lab to open an example notebook.

Source installation

For Mac/Linux users, installation of binaries via pip is by far the easiest option and is strongly recommended. However, if necessary, NUPACK can be built from source.

The following are required:

  • C++17 compliant compiler (Clang or AppleClang)
  • CMake

On Mac, it is recommended to use the Clang provided by Homebrew as it is generally kept more up to date than Apple’s builtin version. After installing Homebrew, install Clang via brew install llvm. Then add the flag -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ or -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++ to your cmake command (use the one corresponding to where brew installed binaries).


  1. On a Mac/Linux system, navigate to the source directory within the NUPACK download:
cd ~/Downloads/nupack-VERSION/source

Make sure to replace nupack-VERSION with the correct folder name (e.g., nupack-4.0.0).

  1. Build the included vcpkg submodule using:

or if you are using a Mac and have not previously installed a C++ compiler, using the following flags:

./external/vcpkg/ --useSystemBinaries --allowAppleClang
  1. Next install the dependencies for NUPACK compilation using vcpkg:
./external/vcpkg/vcpkg install gecode armadillo tbb nlohmann-json jsoncpp taskflow protobuf \
    tclap spdlog fmt boost-context boost-graph boost-align boost-coroutine2 boost-algorithm libsimdpp magic-enum  \
    boost-variant boost-thread boost-sort boost-geometry boost-odeint boost-ublas boost-exception yaml-cpp boost-algorithm
  1. Make a build directory and navigate into it:
mkdir build
cd build
  1. Run the CMake configuration:
cmake .. -DCMAKE_BUILD_TYPE=Release

You may add custom compilation options as flags to the cmake command if desired. Some examples might be:

  • Add -DCMAKE_CXX_COMPILER=clang++ to use the clang++ compiler. As noted above, compilers besides clang are not generally supported.
  • Add -DREBIND_PYTHON=/usr/local/bin/python3 to build for a specific Python executable (by default, the python in the user’s $PATH is used).
  • Add -DCMAKE_CXX_FLAGS="<custom compile options>" to add custom C++ compilation flags.
  • Add -DCMAKE_POSITION_INDEPENDENT_CODE=ON in the offchance you run into a compilation error asking you to recompile with -fPIC.
  1. Build the C++ code:
cmake --build . --target nupack-python
  1. Install the NUPACK Python module:
pip3 install .