Packaging

Guidelines for packaging Nicotine+ for various distributions and platforms

For distribution packagers: GitHub provides a standard feature to be notified of new package releases. Click the Watch option in the top right bar and select releases only to subscribe. This ensures you won’t miss any new releases.

Dependencies

Dependencies for Nicotine+ are described in DEPENDENCIES.md.

GNU/Linux Packaging

Building a Source Distribution

To build a source distribution archive .tar.gz from the Git repository:

1. Run the build command

   python3 -m build --sdist
   
2. Locate the archive

   The source distribution archive will be located in the dist/ subfolder.

Building a Debian Package

Unstable and stable PPAs are already provided for pre-compiled packages. Use these instructions if you wish to build your own package.

1. Install build dependencies

   sudo apt build-dep .
   
2. Generate the upstream tarball

   python3 -m build --sdist
   mk-origtargz dist/nicotine-plus-*.tar.gz
   
3. Build the Debian package

   debuild -sa -us -uc
   

Windows Packaging

GitHub Actions currently builds Nicotine+ installers for Windows. These instructions are useful if you wish to generate an installer on your own machine.

Building a Frozen Application with cx_Freeze

1. Install MSYS2

   Follow the instructions on installing MSYS2. Once installed, launch the CLANG64 environment.

2. Clone the repository

   pacman -S git
   git clone https://github.com/nicotine-plus/nicotine-plus
   cd nicotine-plus
   
3. Install dependencies

   export ARCH=x86_64
   pacman --noconfirm -S --needed mingw-w64-clang-$ARCH-python
   python3 build-aux/windows/dependencies.py
   
4. Build the application

   python3 build-aux/windows/setup.py bdist_msi
   
5. Locate the build

   When the application has finished building, it is located in the build-aux\windows\build\ subfolder.

   To run the application, launch the executable build-aux\windows\build\package\Nicotine+\Nicotine+.exe.

macOS Packaging

GitHub Actions currently builds Nicotine+ packages for macOS. These instructions are useful if you wish to generate a package on your own machine.

Building a Frozen Application with cx_Freeze

1. Install Homebrew

   Follow the instructions on installing Homebrew.

2. Clone the repository

   git clone https://github.com/nicotine-plus/nicotine-plus
   cd nicotine-plus
   
3. Install dependencies

   brew install python@3.14
   python3.14 -m venv venv
   venv/bin/python3 build-aux/macos/dependencies.py
   
4. Build the application

   venv/bin/python3 build-aux/macos/setup.py bdist_dmg
   
5. Locate the build

   When the application has finished building, it is located in the build-aux/macos/build/ subfolder as a .dmg file.