Create a workspace environment#

This tutorial creates a conda.toml project and lets conda-workspaces manage its environment.

Before you start#

Complete the Quickstart, open a local folder in VS Code, and register that folder as a Python project.

Quick create the workspace#

Open the Python Environments view.
Start Quick Create for the project.
Select Conda Code if VS Code asks for an environment manager.

Conda Code runs conda workspace quickstart with the conda manifest format. The project gains a conda.toml file and an installed default environment with Python.

The manifest starts with the same basic shape as:

[workspace]
name = "example"
channels = ["CONFIGURED_CHANNEL"]
platforms = ["linux-64", "osx-arm64", "win-64"]

[dependencies]
python = "*"

The channel and exact platforms come from the configured conda installation and conda-workspaces.

Add a dependency#

Open Manage Packages for the workspace environment and add pytest.

Conda Code routes the change through conda workspace add. The dependency is recorded in the manifest and the installed environment is updated.

conda workspace list

The package view labels packages as direct or transitive dependencies.

Declare a task#

Add this task to conda.toml and save the file:

[tasks]
python-version = { cmd = "python --version", description = "Show the Python version" }

Run a task#

Select the workspace’s default environment in the Python Environments view.
Open the Command Palette.
Run Tasks: Run Task.
Select python-version from the conda-workspaces source.

VS Code opens a task terminal. Conda Code delegates execution to:

conda task --file /path/to/conda.toml run --environment=default -- python-version

Conda Code passes the matching selected workspace environment. conda-workspaces resolves the task graph and runs the declared command.

Clean and reinstall#

Delete the environment from the Python Environments view. Conda Code runs the workspace clean operation, which removes the installed prefix but keeps the environment declaration.

Run Python Envs: Create Environment for the same project. Conda Code finds the declared but uninstalled environment and installs it again.

What happened#

The manifest, not the prefix alone, defines the workspace. Conda Code keeps the environment visible through the same provider as regular conda environments, then chooses workspace commands whenever that manifest is the single source reporting the prefix. It also surfaces the manifest’s tasks through VS Code while leaving task execution to conda-workspaces.