Skip to main content
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
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:
  • 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.)
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

/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.

Build docs developers (and LLMs) love

Get started for freeTalk to us