Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prefix-dev/pixi/llms.txt

Use this file to discover all available pages before exploring further.

Interact with tasks in the workspace. Tasks are commands that can be run with pixi run.

​
Usage

pixi task <SUBCOMMAND>

​
Subcommands

​
add

Add a new task to the workspace. 
pixi task add [OPTIONS] <NAME> <COMMAND>...
Alias: pixi task a

​
Arguments

​
NAME
string
required
Task name.
​
COMMAND
string
required
One or more commands to execute.

​
Options

​
--depends-on
string
Tasks that this task depends on. Multiple dependencies can be specified.
​
--platform
string
The platform for which the task should be added.
​
--feature
string
The feature for which the task should be added.
​
--cwd
path
The working directory relative to the root of the workspace.
​
--env
key=value
Environment variables to set. Use multiple times for multiple variables.Example: --env KEY=value
​
--default-environment
string
Add a default environment for the task.
​
--description
string
A description of the task.
​
--clean-env
boolean
Isolate the task from the shell environment, only using the pixi environment.
​
--arg
string
Arguments to pass to the task. Can be specified multiple times.

​
Examples

# Add a simple task
pixi task add test "pytest -s"

# Add a task with dependencies
pixi task add build "cargo build" --depends-on install-deps

# Add a task with environment variables
pixi task add start "python app.py" --env PORT=8000 --env DEBUG=true

# Add a task with a custom working directory
pixi task add docs "mkdocs serve" --cwd docs

# Add a platform-specific task
pixi task add build-windows "msbuild" --platform win-64

# Add a task with a description
pixi task add deploy "./deploy.sh" --description "Deploy to production"

​
remove

Remove a task from the workspace. 
pixi task remove [OPTIONS] <TASK_NAME>...
Aliases: pixi task rm

​
Arguments

​
TASK_NAME
string
required
Task name(s) to remove. Multiple task names can be specified.

​
Options

​
--platform
string
The platform for which the task should be removed.
​
--feature
string
The feature for which the task should be removed.

​
Examples

# Remove a task
pixi task remove test

# Remove multiple tasks
pixi task remove test build deploy

# Remove a platform-specific task
pixi task remove build-windows --platform win-64

​
alias

Create an alias for other tasks. 
pixi task alias [OPTIONS] <ALIAS> <DEPENDS_ON>...
Alias: pixi task @

​
Arguments

​
ALIAS
string
required
The alias name.
​
DEPENDS_ON
string
required
Tasks that this alias depends on (the tasks to execute).

​
Options

​
--platform
string
The platform for which the alias should be added.
​
--description
string
The description of the alias task.

​
Examples

# Create an alias that runs multiple tasks
pixi task alias ci test lint build

# Create an alias with a description
pixi task alias check test lint --description "Run all checks"

​
list

List all tasks in the workspace. 
pixi task list [OPTIONS]
Aliases: pixi task ls, pixi task l

​
Options

​
--summary
boolean
Show tasks available for this machine per environment.
​
--environment
string
The environment for which tasks should be listed. If not specified, the default environment is used.
​
--json
boolean
Output the list of tasks as JSON instead of a tree.

​
Examples

# List all tasks
pixi task list

# List tasks as a summary
pixi task list --summary

# List tasks for a specific environment
pixi task list --environment production

# List tasks as JSON
pixi task list --json

​
Task Configuration

Tasks can be configured with various options in pixi.toml: 
[tasks]
test = "pytest tests/"

build = { cmd = "cargo build --release", depends-on = ["install-deps"] }

start = { cmd = "python app.py", env = { PORT = "8000" }, cwd = "src" }

deploy = { cmd = "./deploy.sh", description = "Deploy to production" }

ci = { depends-on = ["test", "lint", "build"] }

​
Task Types

​
Plain Tasks

Simple command strings: 
[tasks]
test = "pytest"

​
Complex Tasks

Tasks with additional configuration: 
[tasks]
build = { cmd = "cargo build", cwd = "rust", env = { RUST_BACKTRACE = "1" } }

​
Alias Tasks

Tasks that run other tasks: 
[tasks]
ci = { depends-on = ["test", "lint", "build"] }

​
Task Execution Order

When a task has dependencies, pixi executes them in topological order: 
[tasks]
install-deps = "pip install -r requirements.txt"
test = { cmd = "pytest", depends-on = ["install-deps"] }
build = { cmd = "python setup.py bdist_wheel", depends-on = ["test"] }
Running pixi run build will execute: install-deps → test → build
Use pixi run --skip-deps to skip running task dependencies.

​
Platform-Specific Tasks

You can define tasks that only run on specific platforms: 
[target.win-64.tasks]
build = "msbuild"

[target.linux-64.tasks]
build = "make"

​
Task Arguments

Tasks can accept arguments: 
[tasks]
greet = { cmd = "echo Hello $1", args = ["name"] }
Run with: pixi run greet World
Task commands can use template variables like {{ pixi.platform }} when run with --templated.

​
Best Practices

  1. Use descriptive names: Choose clear, meaningful task names
  2. Add descriptions: Help others understand what each task does
  3. Leverage dependencies: Chain tasks together with depends-on
  4. Keep tasks simple: Break complex operations into multiple tasks
  5. Use environment variables: Make tasks configurable with env vars

Build docs developers (and LLMs) love

Get started for freeTalk to us