aioslsk

aioslsk is a Python library for the SoulSeek protocol built on top of asyncio.

Supported Python versions are currently 3.11 - 3.15

You can find the full documentation here

Installation

pip install aioslsk

Quick Start

Starting the client and sending a private message:

import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand
from aioslsk.settings import Settings, CredentialsSettings

# Create default settings and configure credentials
settings: Settings = Settings(
    credentials=CredentialsSettings(
        username='my_user',
        password='Secret123'
    )
)

async def main():
    client: SoulSeekClient = SoulSeekClient(settings)

    await client.start()
    await client.login()

    # Send a private message
    await client.execute(PrivateMessageCommand('my_friend', 'Hi!'))

    await client.stop()

asyncio.run(main())

Development

Install poetry and setup the project dependencies by running:

poetry install

A tool is available to start the client for debugging purposes (try out commands to the server, …):

Create a settings.json file containing valid credentials in the tools/debug/ directory (or pass a path using --settings). To generate a simple settings file:
```
poetry run python -m aioslsk.settings generate -u "Hello" -p "World" > tools/debug/settings.json
```

To start the REPL run:

# Reads from tools/debug/settings.json
poetry run python -m tools.debug.debug_mode
# Reads from specific file
poetry run python -m tools.debug.debug_mode --settings ~/custom_settings.json

Run an example command (the aioslsk.commands module is aliased to the cmds variable):
```
await client(cmds.GetPeerAddressCommand('some user'), response=True)
```
To close the REPL execute exit() or press Ctrl+Z

Optionally the script takes a --cache-dir that will read/write the transfer and shares cache from the given directory

Building the documentation

cd docs/
poetry run make html

Running Tests

Running all tests:

poetry run pytest tests/

Running all tests with code coverage report:

poetry run pytest --cov=aioslsk --cov-report term-missing tests/

By default the logs are only shown in case of failure. To enable all logging output during testing run the tests as follows:

poetry run pytest tests/ -o log_cli=true

Mock Server

A mock server implementation is available for testing, to start the server run:

# By default the server listens on port 2416
poetry run python -m tests.e2e.mock.server
# Specifying multiple listening ports
poetry run python -m tests.e2e.mock.server --port 2416 2242

Configure the hostname or IP of the server in your client and connect. If such configuration is not possible you can add an entry to the hosts file of your system. For example:

127.0.0.1      server.slsknet.org

Use --help to get a list of available options.

Dependencies

The package uses several dependencies:

mutagen : library used for extracting audio metadata
aiofiles : asyncio library for filesystem management
async-upnp-client : library for managing UPnP configuration
pydantic-settings : library for managing settings
async-timeout : library providing timeout class

Metadata

Release files for aioslsk 1.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aioslsk 1.7.1
File	Size	Uploaded
aioslsk-1.7.1.tar.gz	115.4 kB	Oct 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aioslsk 1.7.1
File	Interpreter	ABI	Platform	Reset
aioslsk-1.7.1-py3-none-any.whl 132.0 kB Oct 11, 2026	Python 3	none	any	Details

Total release size: 247.4 kB

Release files / aioslsk-1.7.1.tar.gz

Download URL	aioslsk-1.7.1.tar.gz
Size	115.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`a7565130f696f5c1c5183da05d6d943af5f174e6f77a5a1b4f80c48dfcdccaa6`
BLAKE2b-256 checksum How to use checksums	`78d092239e62403271503fb82fbbb5debb153abc7e0023387b9c4e9a303d0757`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.0 CPython/3.12.3 Linux/6.17.0-1022-azure`

Release files / aioslsk-1.7.1-py3-none-any.whl

Download URL	aioslsk-1.7.1-py3-none-any.whl
Size	132.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aac554b5e3574614e46438e08638a2d33e99a06f02d87fba1c93302070d33a47`
BLAKE2b-256 checksum How to use checksums	`2d83b460a71ab7de7ad7841411041573f9d7cbdc5bac85fedcf0d39a7293a471`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.0 CPython/3.12.3 Linux/6.17.0-1022-azure`