pixi-task

Create a new task

$ pixi task add [task_name] [task_command]

$ pixi task list

$ pixi task remove [task_name]

$ pixi task alias [alias_name] [task1 task2 ...]

pixi task [OPTIONS] <TASK_NAME> [TASK_ARGUMENTS...]
pixi task [OPTIONS] --list
pixi task [OPTIONS] --info <TASK_NAME>

<TASK_NAME>
    Specifies the name of the task to be executed, as defined in the pixi.toml file.

[TASK_ARGUMENTS...]
    Any additional arguments provided after the task name are passed directly to the command or script executed by the task.

--list, -l
    Lists all available tasks defined in the current pixi project's pixi.toml file.

--info <TASK_NAME>, -i <TASK_NAME>
    Displays detailed information about a specific task, including its command, dependencies, and type.

--frozen
    Prevents any modifications to the pixi.lock file during task execution, ensuring a fully reproducible environment state.

--cwd <PATH>
    Specifies the current working directory from which the task should be executed. This overrides the default project root.

--target <PLATFORM>
    Specifies the target platform for which the task should be executed (e.g., 'linux-64', 'win-64').

The pixi-task command is a subcommand of the pixi package manager, designed to execute project-specific tasks defined within a pixi.toml configuration file. It provides a convenient way to encapsulate and run common development, testing, or build commands in a reproducible and isolated environment managed by pixi.

When invoked, pixi-task locates the pixi.toml file in the current directory or its parent directories, parses the defined tasks, and executes the specified one. Tasks can range from simple shell commands to complex scripts, and they automatically inherit the dependencies and environment setup by pixi for the project. This ensures that tasks run consistently regardless of the system's global environment.

Beyond simple execution, pixi-task supports listing available tasks, displaying detailed information about specific tasks, and passing additional arguments directly to the underlying command. It's a fundamental tool for streamlining project workflows, automating repetitive actions, and maintaining consistent development practices across teams.

The pixi-task command requires a pixi.toml file to be present in the current or a parent directory, as tasks are defined within this configuration. Task execution is contingent on the correct environment setup by pixi; issues with dependencies or environment resolution can prevent a task from running successfully. Arguments passed to a task (TASK_ARGUMENTS) are interpreted by the underlying command executed by the task, not by pixi-task itself.

Tasks are defined under the [tasks] section of the pixi.toml file. Each task can be a simple string (shell command), a table with more options (e.g., cmd, depends_on, install_from_channels), or even a combination. For example:
[tasks]
start = "python app.py"
test = { cmd = "pytest", depends_on = ["lint"] }
lint = "black ."
This structure allows for complex workflows where tasks can depend on each other, ensuring a specific execution order.

One of the key strengths of pixi-task is its deep integration with pixi's managed environment. When a task is executed, pixi automatically ensures that all necessary dependencies specified in the pixi.toml are available and that the task runs within this isolated environment. This means commands like python or pytest inside a task will refer to the versions installed by pixi for that specific project, rather than any globally installed versions. This guarantees reproducibility and avoids conflicts between different projects or system-wide installations.

pixi-task is an integral part of the pixi project, which emerged from the prefix-dev ecosystem as a next-generation package manager aiming to provide reproducible, cross-platform environments. From its inception, the ability to define and execute project-specific tasks has been a core design principle of pixi, addressing the need for streamlined development workflows in modern software projects. Its development closely mirrors the evolution of the broader pixi tool, continuously enhancing its capabilities for task management and environment integration.

pixi(1), make(1), npm-run-script(1)