Setting Up Your Environment#

A guide to getting your development environment set up for working with Tools for Experiments.

Option 1: Using uv#

What is uv?#

uv is a fast Python package and project manager written in Rust, developed by Astral (the team behind ruff). It serves as a drop-in replacement for pip, pip-tools, virtualenv, and more — but orders of magnitude faster.

Key concepts:

pyproject.toml: The single source of truth for your project’s dependencies and metadata, following the modern Python packaging standard.
uv.lock: A lockfile automatically generated by uv that pins exact versions of all dependencies (direct and transitive) for reproducible environments.
Editable installs: uv supports installing local packages in editable mode (editable = true), meaning changes to the source code of those packages are immediately reflected without reinstalling.
Virtual environments: uv automatically creates and manages a .venv in your project directory.

Installing uv#

curl -LsSf https://astral.sh/uv/install.sh | sh

Or via pip:

pip install uv

Project structure: `pyproject.toml`#

Each measurement or experiment folder should have a pyproject.toml that declares its dependencies. For packages that live locally on your machine (like instrumentserver or labcore), use [tool.uv.sources] to point uv to their local paths with editable installs:

[project]
name = "testing-uv-env"          # (1) change to your project name
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "instrumentserver",           # (2) list every package you need here
    "labcore",                    #     one string per package, comma-separated
]

[tool.uv.sources]
# (3) for each local package listed above, add an entry here pointing to its
#     location on your machine. Paths are relative to this pyproject.toml file.
instrumentserver = { path = "../../github/instrumentserver", editable = true }
labcore = { path = "../../github/labcore", editable = true }

What you need to change:

name — set it to something that identifies your experiment or measurement folder.
dependencies — list all packages your code needs. Regular PyPI packages (e.g. numpy, matplotlib) just go here as plain strings and uv will fetch them automatically. Local packages also go here — they need a matching entry in [tool.uv.sources].
[tool.uv.sources] — for every local package in dependencies, add a line with the relative path from this pyproject.toml to that package’s root directory (the folder that contains its own pyproject.toml or setup.py). Keep editable = true so that code changes in those repos take effect immediately.

For example, if your experiment folder is at ~/projects/my-experiment/ and labcore is cloned at ~/github/labcore/, the relative path would be ../../github/labcore.

Creating and syncing the environment#

From the directory containing your pyproject.toml, run:

uv sync

This will:

Create a .venv virtual environment in the current directory (if it doesn’t exist).
Install all dependencies listed in pyproject.toml.
Install the local editable packages from the paths defined in [tool.uv.sources].
Generate or update uv.lock.

Activating the environment#

source .venv/bin/activate

Or run commands directly without activating:

uv run python my_script.py
uv run jupyter lab

Adding new dependencies#

uv add some-package

This updates pyproject.toml and uv.lock automatically.

Option 2: Using conda / mamba#

conda is a cross-platform package and environment manager. mamba is a faster drop-in replacement for conda that uses the same commands and environment files.

Installing conda or mamba#

Miniforge (recommended — ships with mamba by default): Download from github.com/conda-forge/miniforge and follow the installer instructions.
Miniconda (conda only): Download from docs.conda.io/en/latest/miniconda.html.

Creating an environment from the provided file#

A base environment.yml is provided at the root of this repository with a standard set of dependencies:

name: labcore
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.10
  - jupyterlab
  - jupyter_bokeh
  - qcodes=0.44.1
  - bokeh
  - pandas
  - xarray
  - matplotlib
  - numpy=1.26.4
  - scipy
  - scikit-learn
  - seaborn
  - lmfit
  - h5py=3.10.0
  - xhistogram
  - holoviews
  - panel
  - param
  - hvplot
  - versioningit
  - qtpy
  - pip
  - gitpython
  - watchdog
  - pywavelets

To create the environment from it, run from the root of the repository:

conda env create -f environment.yml
conda activate labcore

With mamba (faster):

mamba env create -f environment.yml
mamba activate labcore

Adding or changing dependencies#

If you need extra packages not in environment.yml, install them into the active environment:

conda install -c conda-forge some-package

For packages only available on PyPI:

pip install some-package

Installing local packages in editable mode#

For local repositories like instrumentserver or labcore, install them in editable mode using pip. Replace the paths below with the actual location of each repo on your machine:

pip install -e /path/to/instrumentserver
pip install -e /path/to/labcore

For example, if your repos live in ~/github/:

pip install -e ~/github/instrumentserver
pip install -e ~/github/labcore

The -e flag means editable — any changes you make to the source code of those packages are immediately active without needing to reinstall.