Skip to main content

pylsl

publish workflow PyPI version

This is the Python interface to the Lab Streaming Layer (LSL). LSL is an overlay network for real-time exchange of time series between applications, most often used in research environments. LSL has clients for many other languages and platforms that are compatible with each other.

Let us know if you encounter any bugs (ideally using the issue tracker on the GitHub project).

Installation

Prerequisites

On all non-Windows platforms and for some Windows-Python combinations, you must first obtain a liblsl shared library. See the liblsl repo documentation for further details.

Get pylsl from PyPI

  • pip install pylsl

Get pylsl from source

This should only be necessary if you need to modify or debug pylsl.

  • Download the pylsl source: git clone https://github.com/labstreaminglayer/pylsl.git && cd pylsl
  • From the pylsl working directory, run pip install ..
    • Note: You can use pip install -e . to install while keeping the files in-place. This is convenient for developing pylsl.

Usage

See the examples in src/pylsl/examples. Note that these can be run directly from the commandline with (e.g.) python -m pylsl.examples.{name-of-example}.

You can get a list of the examples with python -c "import pylsl.examples; help(pylsl.examples)"

liblsl loading

pylsl will search for liblsl first at the filepath specified by an environment variable named PYLSL_LIB, then in the package directory (default location for Windows), then finally in normal system library folders.

If the shared object is not installed onto a standard search path (or it is but can't be found for some other bug), then we recommend that you copy it to the pylsl installed module path's lib subfolder. i.e. {path/to/env/}site-packages/pylsl/lib.

  • The site-packages/pylsl path will only exist after you install pylsl in your Python environment.
  • You may have to create the lib subfolder.
  • Use python -m site to find the "site-packages" path.
  • Use cp -L on platforms that use symlinks.

Alternatively, you can use an environment variable. Set the PYLSL_LIB environment variable to the location of the library or set LD_LIBRARY_PATH to the folder containing the library. For example,

  1. PYLSL_LIB=/usr/local/lib/liblsl.so python -m pylsl.examples.{name-of-example}, or
  2. LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib python -m pylsl.examples.{name-of-example}

Binary data in string streams

LSL's cf_string format is really a variable-length blob format ("variable-length ASCII strings or data blobs, such as video frames" in liblsl's own words), and it is length-delimited on the network and in XDF files. pylsl treats it that way:

  • A cf_string outlet accepts str (UTF-8 encoded for you) or any bytes-like object (bytes, bytearray, memoryview) per channel, sent as is. Values may contain NUL bytes.
  • A cf_string inlet returns decoded str by default. With as_numpy=True (on the inlet or per pull_chunk call) it returns the raw bytes of each value with no decoding, as a dtype=object numpy array.
info = pylsl.StreamInfo("frames", "Video", 1, 0, pylsl.cf_string, "cam0")
outlet = pylsl.StreamOutlet(info)
outlet.push_sample([frame_bytes])

inlet = pylsl.StreamInlet(pylsl.resolve_byprop("name", "frames")[0], as_numpy=True)
sample, ts = inlet.pull_sample()  # sample[0] is the bytes object, unchanged

With as_numpy=True the values come back as bytes inside a dtype=object numpy array, and nothing has been decoded. If a value is text, decode it yourself; if you want plain Python containers, use .tolist():

sample, ts = inlet.pull_sample()  # 1-D object array, one bytes per channel
text = sample[0].decode("utf-8")  # or "latin-1", or whatever the sender used
blobs = sample.tolist()  # list of bytes

chunk, ts = inlet.pull_chunk()  # 2-D object array (n_samples, n_channels)
first_channel_text = [b.decode("utf-8") for b in chunk[:, 0]]
rows = chunk.tolist()  # list of lists of bytes

Decoding is the receiver's decision because only the receiver knows what the bytes mean. Other LSL clients that read string streams through C-string APIs will still stop at the first NUL; that is a limitation of those clients, not of the transport.

liblsl compatibility

pylsl and liblsl are versioned independently. Historically they shared version numbers, but that convention ended after the pylsl 1.17.x series: a pylsl version number says nothing about which liblsl release it was built against, and in general you can use the latest pylsl with the latest liblsl.

Minimum supported liblsl: 1.16.0 (i.e. pylsl.library_version() >= 116). pylsl binds lsl_create_outlet_ex unconditionally when it loads the library, and that function was introduced in liblsl 1.16.0. If an older liblsl is loaded, pylsl emits a RuntimeWarning at import time (it does not raise, in case the subset of the API you use still works).

Some features require a newer liblsl than the minimum. Where noted, pylsl detects the capability by looking for the symbol and raises NotImplementedError with an explanatory message if it is absent:

Feature Requires
StreamOutlet(..., transport_flags=...) (lsl_create_outlet_ex) liblsl >= 1.16.0 (the pylsl minimum)
transp_sync_blocking (synchronous zero-copy pushes) liblsl >= 1.18.0
pylsl.set_config_filename() / pylsl.set_config_content() liblsl >= 1.17.7
StreamInfo.reset_uid() liblsl >= 1.18.0
Bulk string free after string-stream pulls (lsl_destroy_string_array) liblsl >= 1.18.0.b4; older liblsl falls back to one lsl_destroy_string call per string (slower, same result)
ContinuousResolver, chunk transfer (push_chunk/pull_chunk) present in every supported liblsl; pylsl degrades gracefully if absent
StreamInlet.pull_chunk(min_samples=...) no extra liblsl requirement (implemented in Python on top of the regular chunk pull)

Note that transp_sync_blocking is a flag value, not a symbol, so pylsl cannot detect its absence: passing it to an older liblsl will simply be ignored or misinterpreted by that library.

Which liblsl do the PyPI wheels bundle?

The platform-specific wheels (win32, win_amd64, macosx_11_0_universal2, manylinux x86_64) bundle the liblsl release named by the LSL_RELEASE / LSL_RELEASE_URL variables at the top of .github/workflows/publish-to-pypi.yml (currently v1.18.0.b5). The pure-Python none-any wheel bundles no library at all; it relies on a liblsl you install yourself (see "liblsl loading" above).

Checking at runtime

import pylsl

pylsl.library_version()  # e.g. 118 -> liblsl 1.18.x
pylsl.library_info()  # build/branch details of the loaded library
pylsl.MIN_LIBLSL_VERSION  # 116 -> the oldest liblsl this pylsl supports

For maintainers

Continuous Integration

pylsl uses continuous integration and distribution. GitHub Actions will upload a new release to pypi whenever a Release is created in GitHub.

The version number is not stored in the source tree; it is derived from the git tag by setuptools-scm (see [tool.setuptools_scm] in pyproject.toml). Creating a GitHub Release with a tag like v1.18.4 is what sets the published version. Before creating the release, review the LSL_RELEASE / LSL_RELEASE_URL variables in both .github/workflows/publish-to-pypi.yml (the liblsl bundled into the platform wheels) and .github/workflows/ci.yml (the liblsl tested against), and update the "liblsl compatibility" section above if the minimum supported liblsl changed.

Linux Binaries Deprecated

We recently stopped building binary wheels for Linux. In practice, the manylinux dependencies were often incompatible with real systems.

Manual Distribution

  1. Manual way:
    1. rm -Rf build dist *.egg-info
    2. uv build (produces the sdist and the pure-Python wheel in dist/)
    3. twine upload dist/*
    • Note: the platform-specific wheels with a bundled liblsl are produced by the publish-to-pypi GitHub Actions workflow, not by this manual path.
  2. For conda
    1. build liblsl: conda build ../liblsl/
    2. conda build .

Known Issues with Multithreading on Linux

  • At least for some versions of pylsl, it has been reported that running on Linux one cannot call pylsl functions from a thread that is not the main thread. This has been reported to cause access violations, and can occur during pulling from an inlet, and also from accessing an inlets info structure in a thread.
  • Recent tests with multithreading (especially when safeguarding library calls with locks) using Python 3.7.6. with pylsl 1.14 on Linux Mint 20 suggest that this issue is solved, or at least depends on your machine. See https://github.com/labstreaminglayer/pylsl/issues/29

Acknowledgments

Pylsl was primarily written by Christian Kothe while at Swartz Center for Computational Neuroscience, UCSD. The LSL project was funded by the Army Research Laboratory under Cooperative Agreement Number W911NF-10-2-0022 as well as through NINDS grant 3R01NS047293-06S1. pylsl is maintained primarily by Chadwick Boulay. Thanks for contributions, bug reports, and suggestions go to Bastian Venthur, David Medine, Clemens Brunner, and Matthew Grivich.

Metadata

Release files for pylsl 1.18.7

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

Source distribution (sdist)

Source distribution for pylsl 1.18.7
File Size Uploaded Provenance Actions
pylsl-1.18.7.tar.gz 48.4 kB Without provenance Details for pylsl-1.18.7.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pylsl 1.18.7
File Actions
pylsl-1.18.7-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for pylsl-1.18.7-py3-none-win_amd64.whl
pylsl-1.18.7-py3-none-win32.whl Python 3 none Windows x86-32 Details for pylsl-1.18.7-py3-none-win32.whl
pylsl-1.18.7-py3-none-manylinux_2_35_x86_64.whl Python 3 none Linux glibc 2.35+ x86-64 Details for pylsl-1.18.7-py3-none-manylinux_2_35_x86_64.whl
pylsl-1.18.7-py3-none-macosx_11_0_universal2.whl Python 3 none macOS 11.0+ universal2 (ARM64, x86-64) Details for pylsl-1.18.7-py3-none-macosx_11_0_universal2.whl
pylsl-1.18.7-py3-none-any.whl Python 3 none any Details for pylsl-1.18.7-py3-none-any.whl

Total release size: 2.8 MB

Release files / pylsl-1.18.7.tar.gz

Download URL pylsl-1.18.7.tar.gz
Size 48.4 kB
Tags Source
SHA-256 checksum
How to use checksums
88dad3856b7956b54105d8cff17018a5c507447af4376527012bbca864401d44
BLAKE2b-256 checksum
How to use checksums
b2c81832ef377d4ea7d436aa9f600709fa4d681eb9db5420603daf41cbe839a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pylsl-1.18.7-py3-none-win_amd64.whl

Download URL pylsl-1.18.7-py3-none-win_amd64.whl
Size 340.9 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
268de82cde17aac96f852ffb4ead4abb34f811546e39f924e04e7a7df9e29ac0
BLAKE2b-256 checksum
How to use checksums
98fbf522aea082f0b70e109bb0b491fe52514fa809c94a117f7a1172e7f3e998
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pylsl-1.18.7-py3-none-win32.whl

Download URL pylsl-1.18.7-py3-none-win32.whl
Size 302.4 kB
Tags Python 3 Windows x86-32
SHA-256 checksum
How to use checksums
728ad7f3551fccaacaf340a2b8dc609b04e88069227d994dd0c1a0aa648ae7d0
BLAKE2b-256 checksum
How to use checksums
8e87d00f6595058f074b0a4bce937f8d45712fe5ffc4c2bd698482b2b728cf29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pylsl-1.18.7-py3-none-manylinux_2_35_x86_64.whl

Download URL pylsl-1.18.7-py3-none-manylinux_2_35_x86_64.whl
Size 1.3 MB
Tags Linux glibc 2.35+ x86-64 Python 3
SHA-256 checksum
How to use checksums
6045b4a0184399b8aa39678c02dd34b928b6628dac6737d9521df285cd277bf6
BLAKE2b-256 checksum
How to use checksums
3a55f290d317979e526253b37edb210dffa80cc08ccd2e7e33d25839f8bec6b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pylsl-1.18.7-py3-none-macosx_11_0_universal2.whl

Download URL pylsl-1.18.7-py3-none-macosx_11_0_universal2.whl
Size 738.2 kB
Tags Python 3 macOS 11.0+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
74d2da8c627459b9a77284fd6d839034f702dc44dade370b6d5aec7c615fe71b
BLAKE2b-256 checksum
How to use checksums
ac1155f59c5d3d2066133286cd92b29a2bedfd0b1947e2a3a04dd9c1d31d6a3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pylsl-1.18.7-py3-none-any.whl

Download URL pylsl-1.18.7-py3-none-any.whl
Size 50.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75fca7e885e0bbe3a60530a779c2b9763db77bf268148400b5dc5afc20d15115
BLAKE2b-256 checksum
How to use checksums
29d906c9cbd72993df3d84c52bf6c2d0f4c3e34dea8bdc0097e04b5945f3e8cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pylsl 1.18.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.18.7 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page