Downloads & Uploads

Manage file transfers including downloads, uploads, and queue management

Nicotine+ provides comprehensive file transfer management with support for queuing, resuming, and bandwidth control.

Downloads

Starting Downloads

You can initiate downloads from multiple sources:

Search Results

1. Perform a search using the Search tab
2. Select desired files from results
3. Click “Download” or press Enter
4. Files are added to the download queue

User Browse

1. Browse a user’s shared files
2. Navigate to desired folders
3. Right-click and select “Download Folder” or “Download Files”
4. Entire folder structures can be downloaded

Direct Request

1. Right-click a user
2. Select “Download from User”
3. Enter file path manually (advanced)

Download Process

1. Queue File

   When you request a download:

   • Download is validated against filters
   • File is checked for duplicate
   • QueueUpload message sent to user
   • Status set to “Queued” or “Paused”
2. Wait in Queue

   Your download waits for:

   • User to accept your queue request
   • Your position in their upload queue
   • User’s upload slots to become available
   • Network connectivity to be established
3. Transfer Begins

   When your turn arrives:

   • User sends TransferRequest
   • File connection is established
   • Download starts from byte offset (for resume)
   • Progress updates in real-time
4. File Completion

   After transfer completes:

   • File moved from incomplete to download folder
   • Completion notification displayed
   • After-finish command executed (if configured)
   • Statistics updated

Download States

Downloads can be in various states:

Download Status Meanings

Queued: Waiting in the remote user’s upload queue

Transferring: Actively downloading

Paused: Manually paused by you

Finished: Transfer completed successfully

Filtered: Blocked by download filter

User Logged Off: Remote user is offline

Connection Closed: Network connection failed

Connection Timeout: Remote user didn’t respond

File Not Shared: File no longer in user’s shares

Cancelled: User rejected your download request

Download Folder Error: Can’t write to download folder

Local File Error: File I/O error during transfer

Download Management

Queue Actions

Right-click downloads to:

Retry: Re-queue failed downloads

Pause: Temporarily stop download

Abort: Cancel download and remove from queue

Clear: Remove finished/failed downloads from list

Browse User: View the user’s shared files

Send Message: Open private chat with user

Folder Actions

Manage download folders:

Set Download Folder: Choose destination per-file or per-folder

Open Folder: Browse to download location

Username Subfolders: Automatically organize by user

Folder Completion: Run scripts when folders finish

Advanced Options

Resume Support: Automatically resume interrupted downloads

Retry Failed: Auto-retry connection/I/O errors

Clear Finished: Auto-remove completed downloads

Queue Position: Request your position every 5 minutes

Download Filters

Prevent unwanted downloads using filters:

Creating Filters

1. Open Filter Settings

   Navigate to Preferences > Downloads > Filters

2. Add Filter Pattern

   Enter filter patterns using wildcards:

   *.exe          - Block executable files
   *.rar          - Block RAR archives  
   *virus*        - Block files with "virus" in name
   
3. Set Filter Type

   Choose between:

   • Escaped: Treat pattern literally with wildcards
   • Regex: Use regular expression (advanced)
4. Enable Filters

   Toggle “Enable Download Filters” to activate

Filtered downloads are automatically blocked. You can bypass filters by selecting a single filtered download and clicking Retry.

Uploads

Upload Queue System

Nicotine+ manages uploads using a sophisticated queue:

FIFO Queue: First-in, first-out order

Round Robin: Rotate between users fairly

Privileged Users: Priority for privileged/prioritized users

Upload Process

1. Receive Request

   When a user requests a file:

   • Permission level checked (banned, buddy, public)
   • File availability verified
   • Queue limits checked
   • QueueUpload or TransferRequest processed
2. Queue Management

   Upload enters queue based on:

   • User privilege status
   • Current queue size
   • Upload slot availability
   • Bandwidth limits
3. Transfer Start

   When slot becomes available:

   • TransferRequest sent to downloader
   • File connection established
   • Upload begins from requested offset
   • Speed limited per configuration
4. Completion

   After upload finishes:

   • Upload speed reported to server
   • Statistics updated
   • Next queued upload starts automatically

Upload Limits

Control upload behavior with limits:

Slot Limits

Upload Slots: Maximum simultaneous uploads

Default: 2 slots

Behavior: New uploads wait for free slots

Note: Privileged users can bypass some limits

Queue Limits

File Limit: Max files per user in queue

Queue Size Limit: Max megabytes per user

Exemptions: Buddies can bypass limits if configured

Speed Limits

Upload Bandwidth: Total KB/s limit

Per-Transfer: Automatic division among active uploads

Alternative Limit: Switch between two preset limits

Limit By: Total bandwidth or per-transfer

Upload States

Upload Status Meanings

Queued: Waiting for upload slot

Transferring: Actively uploading

Finished: Transfer completed

Cancelled: Stopped by you or downloader

User Logged Off: Downloader disconnected

Connection Timeout: Downloader didn’t respond

File Not Shared: File removed from shares

File Read Error: Can’t read file from disk

Banned: User is banned from downloading

Queue Position

Understand how queue positions work:

For Downloads

Your position is determined by:

1. User’s queue system (FIFO or Round Robin)
2. Whether you’re a privileged user
3. How long you’ve been queued
4. Number of other users queued

Nicotine+ automatically requests your queue position every 5 minutes.

For Uploads

You determine positions for others based on:

1. Queue Mode Selection

   Choose between:

   • FIFO: First request gets first upload
   • Round Robin: Cycle between users fairly
2. Privilege Handling

   Privileged users get priority:

   • Privileged server users (donated)
   • Prioritized buddies (your setting)
   • Regular users
3. Position Calculation

   Position updates when:

   • New uploads queued
   • Uploads complete
   • Users request position update

Transfer Performance

Bandwidth Management

Optimize Transfer Speed:

For Downloads:

• Set appropriate download speed limit
• Close bandwidth-heavy applications
• Use wired connection when possible
• Increase upload slots to improve reciprocity

For Uploads:

• Balance slot count vs. speed per transfer
• Use per-transfer limits for fairness
• Monitor actual upload capacity
• Don’t set limits too low (affects reciprocity)

Resume Support

Both downloads and uploads support resuming:

1. Interruption Handling

   If a transfer is interrupted:

   • Current byte offset is saved
   • Incomplete file remains in temp folder
   • Transfer marked with appropriate status
2. Automatic Retry

   Nicotine+ automatically retries:

   • Connection failures (every 3 minutes)
   • I/O errors (every 15 minutes)
   • User logged off (when user returns)
3. Resume Transfer

   When resuming:

   • FileOffset message sent with byte position
   • Transfer continues from last position
   • No data is re-downloaded

Download Destinations

Configure where files are saved:

Default Folder

Set in Preferences > Downloads:

• Main download directory
• Used when no custom folder specified
• Supports environment variables
• Can create username subfolders

Incomplete Folder

Temporary storage during downloads:

• Files saved here during transfer
• Moved to download folder when complete
• Can be same as download folder
• Cleaned up automatically

Custom Folders

Per-download destinations:

• Right-click download
• Select “Set Download Folder”
• Choose custom location
• Entire folder downloaded there

After-Completion Actions

Run scripts when transfers complete:

File Completion

# Linux/Mac example
/path/to/script.sh "$@"

# Windows example
C:\Scripts\process.bat "%@"

The %@ or $@ variable contains the full path to the downloaded file.

Folder Completion

Separate command runs when all files in a folder finish:

# Extract archives automatically
unzip "$@"/*.zip

# Move to media library  
mv "$@" /media/library/

Remote Downloads

Accept files sent directly by other users:

Security Consideration: Remote downloads allow others to send you arbitrary files. Configure carefully:

• Disable entirely (recommended)
• Only allow from buddies
• Only allow from trusted buddies

Files are saved to a separate “Received” folder.

Shutdown After Uploads

Schedule Nicotine+ to quit after uploads finish:

1. Enable Shutdown Mode

   File > Quit After Uploads

2. Continue Normal Operation

   Uploads continue normally

3. Automatic Exit

   When upload queue empties, Nicotine+ exits

New upload requests are rejected with “Pending Shutdown” status.

Transfer Statistics

Nicotine+ tracks detailed statistics:

• Total downloaded/uploaded bytes
• Number of completed transfers
• Average upload speed (reported to server)
• Transfer success/failure rates
• Active transfer count

Troubleshooting

Downloads Not Starting

1. Check you’re not at queue limit for that user
2. Verify user is online and responding
3. Ensure file still exists in their shares
4. Check download filters aren’t blocking
5. Verify download folder is writable

Slow Transfer Speeds

• Remote user’s upload bandwidth limit
• Your download bandwidth limit
• Network congestion
• Firewall/NAT issues
• Too many simultaneous transfers

Uploads Not Processing

1. Check upload slots aren’t full
2. Verify bandwidth limit allows transfers
3. Ensure shares are initialized
4. Check file still exists and is readable
5. Verify remote user can connect