Getting started#

See the plan, then build#

plan reads the request and the dependency files and prints every command, without changing anything:

$ scikitplot env plan -n analysis --package "pandas>=2" --verify-import pandas
plan 3c7c22ba3748  ensure ~/.scikitplot/env/envs/analysis
  target   host
  backend  uv (asked: auto) - PyPI only; uv found at /usr/local/bin/uv
  1. create a uv environment with Python 3.12.4  [network]
     $ uv venv ~/.scikitplot/env/envs/analysis --seed --python 3.12.4
  2. install PyPI packages with uv  [network]
     $ uv pip install --python ~/.scikitplot/env/envs/analysis/bin/python 'pandas>=2'
  3. import pandas
     $ ~/.scikitplot/env/envs/analysis/bin/python -I -c '...' pandas

create runs exactly that plan. Run it again and nothing happens: the environment’s receipt matches the request.

$ scikitplot env create -n analysis --package "pandas>=2" --verify-import pandas
$ scikitplot env create -n analysis --package "pandas>=2" --verify-import pandas
~/.scikitplot/env/envs/analysis: up to date (nothing to do)
$ scikitplot env run -n analysis -- python -c "import pandas; print(pandas.__version__)"

Named environments live under ~/.scikitplot/env/envs (SKPLT_ENV_HOME moves the whole home); -p .venv builds in a directory of your choice.

From Python#

The functions take the same fields as keywords:

import tempfile

from scikitplot import _env

prefix = tempfile.mkdtemp() + "/demo"
plan = _env.plan(prefix=prefix, backend="venv", verify_imports=["json"])
print(plan.render())
assert [step.id for step in plan.steps] == ["create", "verify"]

_env.create(...) returns an ExecutionResult (result.changed is false when there was nothing to do); _env.remove(...) deletes the environment; _env.run(["python", "-V"], ...) runs a command in it.

Conda packages and bootstrapping micromamba#

A Conda package (--conda-package) or an environment.yml selects micromamba, mamba or conda. When none is installed, the builder can install micromamba itself, the conda-forge build checked against a SHA-256 written in the builder, into ~/.scikitplot/env/tools/bin. That needs both the policy and your approval:

$ scikitplot env create -n geo --conda-package gdal --package rasterio \
      --bootstrap if-missing --approve bootstrap

scikitplot env shell-init bash prints the lines that put the tools on PATH and hook micromamba activate into bash; --write --yes adds them to ~/.bashrc between marker lines (running it again changes nothing).