Your first project#

This tutorial walks through setting up a Python project with separate environments for development, testing, and documentation — plus tasks to automate your workflow.

Prerequisites#

  • conda (>= 24.7) with the conda-workspaces plugin installed

  • A project directory to work in

Create the workspace manifest#

Start by creating a conda.toml in your project root:

mkdir my-project && cd my-project
conda workspace init --format conda --name my-project

This creates a conda.toml with sensible defaults:

[workspace]
name = "my-project"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]

Add dependencies#

Add your base dependencies:

conda workspace add "python>=3.10"
conda workspace add "numpy>=1.24" "scipy>=1.11"

Add test dependencies to a test feature:

conda workspace add -e test "pytest>=8.0" "pytest-cov>=4.0"

Add documentation dependencies:

conda workspace add -e docs "sphinx>=7.0" "myst-parser>=3.0"

Your conda.toml now looks like:

[workspace]
name = "my-project"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = ">=3.10"
numpy = ">=1.24"
scipy = ">=1.11"

[feature.test.dependencies]
pytest = ">=8.0"
pytest-cov = ">=4.0"

[feature.docs.dependencies]
sphinx = ">=7.0"
myst-parser = ">=3.0"

[environments]
default = []
test = { features = ["test"] }
docs = { features = ["docs"] }

Install environments#

conda workspace install

This creates three conda environments under .conda/envs/:

.conda/envs/
├── default/    # python, numpy, scipy
├── test/       # + pytest, pytest-cov
└── docs/       # + sphinx, myst-parser

Define tasks#

Add tasks to your conda.toml:

[tasks]
test = { cmd = "pytest tests/ -v", description = "Run the test suite" }
lint = { cmd = "ruff check src/", description = "Lint the source code" }
build-docs = { cmd = "sphinx-build docs docs/_build/html", description = "Build documentation" }

[tasks.check]
depends-on = ["lint", "test"]
description = "Run all checks"

Run tasks#

List available tasks:

conda task list

Run a single task in a workspace environment:

conda task run -e test test

Run the full check suite:

conda task run -e test check

Build documentation:

conda task run -e docs build-docs

Run commands in an environment#

Run a one-shot command in a workspace environment:

conda workspace run -e test -- python -c "import numpy; print(numpy.__version__)"

Or drop into an interactive shell:

conda workspace shell -e test

Check environment status#

conda workspace envs
conda workspace info -e test

Next steps#

On this page
Show Source