Quick Start Guide

Get up and running with Nicotine+ in minutes - from installation to your first download

This guide will walk you through setting up Nicotine+ and performing your first search and download.

Installation

First, download and install Nicotine+ for your operating system:

Windows

Download the installer for Windows 10+

macOS

Download for Intel or Apple Silicon

Linux

Install via package manager

For detailed installation instructions for your specific platform, see the Downloads page.

First Launch

1. Launch Nicotine+

   Start the application from your applications menu or command line:

   nicotine
   

   On first launch, you’ll be greeted with the setup wizard.

2. Create or Log In to Your Soulseek Account

   You need a Soulseek account to connect to the network:

   • New users: Choose a username and password to create an account
   • Existing users: Enter your existing Soulseek credentials

   Your Soulseek account works with any Soulseek client, including the official client and Nicotine+.

3. Configure Basic Settings

   The setup wizard will guide you through essential settings:

   • Download folder: Where files will be saved (e.g., ~/Downloads)
   • Shared folders: Folders you want to share (optional, can be set later)
   • Port settings: For optimal connectivity (automatic by default)

   You can skip sharing files initially and configure this later in Settings.

4. Connect to the Network

   Click Connect to join the Soulseek network. You should see:

   • Connection status change to “Connected”
   • Number of users online
   • Server messages in the log

Your First Search

Once connected, you can start searching for files:

1. Open the Search Tab

   Click the Search tab or use the search bar at the top of the main window.

2. Enter Your Search Query

   Type what you’re looking for (e.g., artist name, album, song title) and press Enter or click Search.

   Miles Davis Kind of Blue
   

   Use specific search terms for better results. You can use filters like file type, size, and bitrate to narrow results.

3. Browse Search Results

   Search results will appear showing:

   • Filename - The file name
   • User - Who is sharing the file
   • Size - File size
   • Speed - Estimated transfer speed
   • Quality - Audio bitrate (for music files)

   Results are sorted by relevance and availability.

4. Download a File

   To download a file:

   1. Right-click on the file you want
   2. Select Download from the context menu

   Or simply double-click the file to start downloading.

   The download will appear in the Downloads tab.

Understanding Download Queue

Nicotine+ uses a queue system for downloads:

Download States

• Queued - Waiting for an upload slot from the user
• Getting status - Requesting file information
• Downloading - Active transfer
• Paused - Transfer paused by you
• Finished - Download complete
• Failed - Transfer failed (user offline, file removed, etc.)

Managing Downloads

Right-click any download to:

• Pause/Resume - Control individual downloads
• Abort - Cancel and remove from queue
• Retry - Attempt download again
• Browse Files - View all files shared by this user
• Send Message - Chat with the user

Upload slots are limited by the file owner. You may need to wait in their queue before your download starts.

Setting Up File Sharing (Optional)

Sharing files helps the community and improves your standing with other users:

1. Open Settings

   Click Settings → Shares or use the menu: Edit → Preferences → Shares

2. Add Shared Folders

   1. Click Add Folder or Add Virtual Folder
   2. Select the folder(s) you want to share
   3. Click OK to confirm

   Virtual folders let you organize shares with custom names instead of using your actual folder structure.

3. Scan Your Shares

   Click Rescan Shares to build the file database. This may take a few minutes depending on the number of files.

   The scan will:

   • Index all files in your shared folders
   • Extract metadata (for audio files)
   • Make files available for other users to search
4. Configure Upload Settings

   In Settings → Transfers → Uploads, you can configure:

   • Upload slots - Number of simultaneous uploads (default: 2)
   • Upload speed limit - Bandwidth throttling
   • Queue settings - How your upload queue behaves

Only share files you have the right to distribute. Respect copyright laws in your jurisdiction.

Command Line Options

Nicotine+ supports several command-line options for advanced usage:

# Start hidden (minimized to tray)
nicotine --hidden

# Start in headless mode (no GUI)
nicotine --headless

# Use custom configuration file
nicotine --config /path/to/config.json

# Use alternative data folder
nicotine --user-data /path/to/data

# Bind to specific IP (useful for VPN)
nicotine --bindip 192.168.1.100

# Listen on specific port
nicotine --port 5000

# Rescan shared files
nicotine --rescan

# Show version
nicotine --version

Run nicotine --help to see all available command-line options.

Joining Chat Rooms

Connect with the community through chat rooms:

1. Open Chat Rooms

   Click the Chatrooms tab in the main window.

2. Join a Room

   1. Click Join Room button
   2. Enter a room name or browse popular rooms
   3. Click Join

   Popular rooms include:

   • music - General music discussion
   • jazz, metal, electronic - Genre-specific rooms
   • help - Get help from experienced users
3. Start Chatting

   • Type messages in the input box at the bottom
   • Right-click usernames to browse their files or send private messages
   • Use /help to see available chat commands

Useful Chat Commands

Basic Commands

/help          # Show all available commands
/me <action>   # Send an action message
/join <room>   # Join a chat room
/part          # Leave current room
/quit          # Disconnect from server

Improving Connection Quality

For optimal performance, configure your network settings:

1. Enable Port Forwarding

   Go to Settings → Network → Connectivity:

   1. Note your listening port (default: random)
   2. Configure port forwarding on your router for this port
   3. Click Test Port to verify connectivity

   Port forwarding is not required but significantly improves download speeds and connectivity.

2. Configure Bandwidth

   In Settings → Transfers:

   • Set download/upload speed limits if needed
   • Adjust number of upload slots based on your connection
   • Enable bandwidth throttling during specific hours
3. Check Connection Status

   A good connection shows:

   • Status: Connected
   • Port Status: Open (green indicator)
   • Server: Connected to Soulseek server

Next Steps

Core Features

Explore advanced file sharing features

Search Tips

Learn advanced search techniques

Network Configuration

Optimize your network settings

User Management

Manage buddies, ignored users, and more

Getting Help

If you run into issues:

• IRC Channel: Join #nicotine+ on Libera.Chat
• Issue Tracker: Report bugs on GitHub
• Help Room: Join the help chat room in Nicotine+
• Documentation: Browse the full documentation on this site

Check the log window (View → Log Window) for detailed error messages when troubleshooting.