Installation¶

This page describes recommended installation paths for playNano. Conda is the recommended default because it gives the most reliable binary support for scientific packages and Qt/PySide.

The latest stable release is available on PyPI as the playnano package as well as through GitHub.

System requirements¶

Python 3.10 - 3.12 (3.11 recommended)
Linux, macOS, or Windows
Internet connection for downloading packages

Note

NumPy is currently pinned to <2.0 for compatibility with some scientific libraries. See the Changelog for updates.

Installation Guide¶

It is recommended that playNano is installed in a virtual environment to ensure dependency isolation, prevent version conflicts with other Python packages, and maintain a clean, reproducible setup across different systems.

Quick Install (recommended: conda)¶

Create a reproducible conda environment and install playNano.

Note

To use the recommended conda-based installation, first install either Miniconda or Anaconda, which provide the conda package manager. Miniconda is lightweight and ideal for custom setups, while Anaconda includes a full suite of scientific packages out of the box.

# 1) Create and activate a conda env
conda create -n playnano_env python=3.11
conda activate playnano_env

# 2) Install the package from PyPI
pip install playnano

Notes & troubleshooting¶

PySide6 / Qt issues If pip installation of PySide6 fails (common on some Windows setups), prefer the conda package:
```
conda install -c conda-forge pyside6
```
AFMReader Required for reading some vendor formats (.jpk, .spm, .asd). If it is not available from PyPI in your environment, install it from GitHub:
```
pip install git+https://github.com/AFM-SPM/AFMReader.git
```
GIF export / metadata Some input files must include metadata (e.g. line_rate). If GIF export fails, check console logs for missing metadata.

Verification¶

After installation, verify CLI and import:

playnano --help

Check version from Python:

python -c "import playnano; print(playnano.__version__)"

Developer install¶

If you wish to change the code or contribute to the project, clone the repository from the GitHub repository and install in “editable” mode. This will give you access to the latest development version and make changes to the codebase.

# 1) Clone the repository (if you haven't already)
git clone https://github.com/derollins/playNano.git
# And navigate to the project root
cd playNano

# 2) Create and activate a conda env
conda create -n playnano_env python=3.11
conda activate playnano_env

# 3) Install the package (from the project root)
pip install -e .

There are additionally optional dependencies that can be installed for particular tasks. To work on the documentation, or run the example notebooks, you can install these as “extras” using pip.

If you are developing or contributing, install the full set of extras, especially the dev group (which includes linting and testing tools).

You can also install optional extras for docs, notebooks, or development:

pip install -e ".[docs]"       # docs build dependencies (Sphinx, theme, nbsphinx)
pip install -e ".[notebooks]"  # notebook/demo dependencies (Jupyter)
pip install -e ".[dev]"        # developer dependencies (linting, testing, pre-commit)

Developer usage¶

Install all of the dependencies for linting, tests, docs and notebooks:

# After cloning the repo and activating your conda env
pip install -e ".[dev,docs,notebooks]"

Run tests:

pytest

Build the docs locally:

sphinx-build docs docs/_build/html

Alternative manual install: pip + venv¶

If you prefer the standard library virtualenv workflow, use venv:

python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install -e .[dev,docs,notebooks]

Install via environment.yaml¶

If you prefer a reproducible setup using a pre-defined environment file, you can use the provided environment.yaml to create a conda environment with all required dependencies.

conda env create -f environment.yaml
conda activate playnano_env

This will install:

Python 3.11 and core scientific libraries (NumPy, SciPy, Pillow, Matplotlib)
AFM-specific tools: afmreader
GUI support via PySide6
Compatibility pins (e.g. h5py=3.8.*) to avoid known issues

Note

The environment uses the conda-forge channel for reliable binary support across platforms.

Tip

If you modify environment.yaml, you can update your environment with:

conda env update -f environment.yaml --prune