pixi workspace

Manage workspace configuration through the command line

The pixi workspace command provides subcommands to modify and query workspace configuration directly from the command line without manually editing the manifest file.

Usage

pixi workspace <SUBCOMMAND> [OPTIONS]

Subcommands

The workspace command includes several subcommands for managing different aspects of your workspace:

• channel - Manage workspace channels
• description - Get or set workspace description
• environment - Manage workspace environments
• export - Export workspace to different formats
• feature - Manage workspace features
• name - Get or set workspace name
• platform - Manage workspace platforms
• requires-pixi - Manage pixi version requirements
• system-requirements - Manage system requirements
• version - Manage workspace version

Channel Management

Add Channel

Add one or more channels to the workspace:

pixi workspace channel add [OPTIONS] <CHANNEL>...

Options:

CHANNEL · string · required

Channel name or URL to add. Multiple channels can be specified.

--priority · integer

Specify the channel priority (higher values = higher priority).

--prepend · boolean · default: "false"

Add the channel(s) to the beginning of the channels list.

--feature · string

Add the channel to a specific feature.

Short flag: -f

--no-install · boolean · default: "false"

Don’t install the environment, only update the lock file.

Examples:

pixi workspace channel add conda-forge
pixi workspace channel add bioconda --prepend
pixi workspace channel add pytorch --priority 100
pixi workspace channel add nvidia --feature cuda

Aliases: pixi workspace channel a

List Channels

List all channels in the workspace:

pixi workspace channel list [OPTIONS]

Options:

--urls · boolean · default: "false"

Display channel URLs instead of names.

Examples:

pixi workspace channel list
pixi workspace channel list --urls

Aliases: pixi workspace channel ls

Remove Channel

Remove one or more channels from the workspace:

pixi workspace channel remove [OPTIONS] <CHANNEL>...

Options:

CHANNEL · string · required

Channel name or URL to remove. Multiple channels can be specified.

--priority · integer

Only remove channels with this priority.

--feature · string

Remove the channel from a specific feature.

Short flag: -f

--no-install · boolean · default: "false"

Don’t install the environment, only update the lock file.

Examples:

pixi workspace channel remove defaults
pixi workspace channel remove pytorch --feature ml

Aliases: pixi workspace channel rm

Description Management

Get Description

Get the workspace description:

pixi workspace description get

Outputs the current workspace description if set.

Set Description

Set the workspace description:

pixi workspace description set <DESCRIPTION>

Examples:

pixi workspace description get
pixi workspace description set "My awesome data science project"

Environment Management

Add Environment

Add a new environment to the workspace:

pixi workspace environment add [OPTIONS] <NAME>

Options:

NAME · string · required

Name of the environment to add.

--feature · string

Features to add to the environment. Can be specified multiple times.

Short flag: -f

--solve-group · string

The solve-group to add the environment to.

--no-default-feature · boolean · default: "false"

Don’t include the default feature in the environment.

--force · boolean · default: "false"

Update the manifest even if the environment already exists.

Examples:

pixi workspace environment add prod
pixi workspace environment add test --feature test-deps
pixi workspace environment add ml --feature ml --feature cuda --solve-group gpu
pixi workspace environment add minimal --no-default-feature

Aliases: pixi workspace environment a

List Environments

List all environments in the workspace:

pixi workspace environment list

Displays all environments with their features and solve groups.

Aliases: pixi workspace environment ls

Remove Environment

Remove an environment from the workspace:

pixi workspace environment remove <NAME>

Examples:

pixi workspace environment list
pixi workspace environment remove old-env

Aliases: pixi workspace environment rm

Feature Management

List Features

List all features in the workspace:

pixi workspace feature list

Displays features with their dependencies, PyPI dependencies, and tasks.

Aliases: pixi workspace feature ls

Remove Feature

Remove a feature from the workspace:

pixi workspace feature remove <FEATURE>

Examples:

pixi workspace feature list
pixi workspace feature remove old-feature

Aliases: pixi workspace feature rm

Name Management

Get Name

Get the workspace name:

pixi workspace name get

Set Name

Set the workspace name:

pixi workspace name set <NAME>

Workspace names should only use lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (_).

Examples:

pixi workspace name get
pixi workspace name set "my-project"
pixi workspace name set "data_analysis_2024"

Platform Management

Add Platform

Add platform(s) to the workspace:

pixi workspace platform add [OPTIONS] <PLATFORM>...

Options:

PLATFORM · string · required

Platform name(s) to add (e.g., linux-64, osx-arm64, win-64).

--no-install · boolean · default: "false"

Don’t update the environment, only add to lock file.

--feature · string

Add the platform to a specific feature.

Short flag: -f

Examples:

pixi workspace platform add linux-64
pixi workspace platform add osx-arm64 win-64
pixi workspace platform add linux-64 --feature cuda --no-install

Aliases: pixi workspace platform a

List Platforms

List all platforms in the workspace:

pixi workspace platform list

Aliases: pixi workspace platform ls

Remove Platform

Remove platform(s) from the workspace:

pixi workspace platform remove [OPTIONS] <PLATFORM>...

Options:

PLATFORM · string · required

Platform name(s) to remove.

--no-install · boolean · default: "false"

Don’t update the environment, only remove from lock file.

--feature · string

Remove the platform from a specific feature.

Short flag: -f

Examples:

pixi workspace platform remove osx-64
pixi workspace platform remove linux-64 --feature old-feature

Aliases: pixi workspace platform rm

Export

Export workspace to different formats:

pixi workspace export <SUBCOMMAND>

See the export subcommands for available formats (e.g., conda environment files).

Requires Pixi

Manage pixi version requirements for the workspace:

pixi workspace requires-pixi <SUBCOMMAND>

Available subcommands:

• get - Get the required pixi version
• set - Set the required pixi version
• unset - Remove the pixi version requirement
• verify - Verify current pixi version meets requirements

System Requirements

Manage system requirements for the workspace:

pixi workspace system-requirements <SUBCOMMAND>

Available subcommands:

• add - Add system requirements
• list - List system requirements

Version Management

Manage workspace version:

pixi workspace version <SUBCOMMAND>

Available subcommands:

• get - Get the workspace version
• set - Set the workspace version
• bump - Bump the workspace version

Global Options

--manifest-path · string

Path to pixi.toml, pyproject.toml, or workspace directory.

Short flag: -m

pixi workspace channel list --manifest-path /path/to/project

Complete Examples

Set Up New Workspace

# Set workspace metadata
pixi workspace name set "ml-project"
pixi workspace description set "Machine learning project with GPU support"
pixi workspace version set "0.1.0"

# Add platforms
pixi workspace platform add linux-64 osx-arm64

# Add channels
pixi workspace channel add conda-forge --prepend
pixi workspace channel add pytorch

# Create environments
pixi workspace environment add prod --feature ml --feature data
pixi workspace environment add dev --feature ml --feature test

Manage Multi-Environment Project

# Add test environment with specific features
pixi workspace environment add test --feature testing --no-default-feature

# Add channels for the test feature
pixi workspace channel add conda-forge --feature testing

# Add platform for testing
pixi workspace platform add linux-64 --feature testing

Inspect Workspace Configuration

# View workspace metadata
pixi workspace name get
pixi workspace description get
pixi workspace version get

# List configurations
pixi workspace channel list
pixi workspace platform list
pixi workspace environment list
pixi workspace feature list

See Also

• pixi init - Initialize a new pixi workspace
• pixi add - Add dependencies to workspace
• pixi remove - Remove dependencies from workspace