pixi run

Run tasks in the pixi environment

Runs a task or command in the pixi environment. This command activates the environment and executes the specified task using the deno_task_shell.

pixi run will automatically update the lockfile and install the environment if required.

Usage

pixi run [OPTIONS] [TASK]...

Alias: pixi r

Arguments

TASK · string

The pixi task or shell command you want to run in the workspace’s environment. Can be an executable in the environment’s PATH.

If no task is specified, pixi will print all available tasks.

Options

--manifest-path · path

The path to the pixi.toml or pyproject.toml file.

--frozen · boolean

Install the environment as defined in the lockfile, without updating it.

--locked · boolean

Check if the lockfile is up-to-date before installing the environment. Errors if the lockfile is out-of-date.

--environment · string

The environment to run the task in.

--executable · boolean

Execute the command as an executable without resolving Pixi tasks.

Useful when a task name and an executable have the same name.

--clean-env · boolean

Use a clean environment to run the task.

This flag will ignore your current shell environment and use a bare minimum environment to activate the pixi environment in.

--skip-deps · boolean

Don’t run the dependencies of the task (tasks defined in the depends-on field).

--templated · boolean

Enable template rendering for the command arguments.

By default, arguments passed to pixi run on the command line are not processed by the template engine. Use this flag to enable rendering of template variables like {{ pixi.platform }}.

--dry-run · boolean

Run the task in dry-run mode (only print the command that would run).

--no-install · boolean

Don’t install the environment, only activate it.

Examples

Run a task

pixi run test

Run a task with arguments

pixi run build --release

Run a command directly

pixi run python script.py

List all available tasks

pixi run

When no task is provided, pixi will display all tasks available in the current environment.

Run an executable by name when a task exists with the same name

pixi run --executable python

Run a task in a specific environment

pixi run --environment production start

Run a task with a clean environment

pixi run --clean-env test

Skip task dependencies

pixi run --skip-deps build

Dry-run mode

pixi run --dry-run deploy

This will print the commands that would be executed without actually running them.

Task Execution

When you run a task:

1. Pixi checks if the lockfile is up-to-date (unless --frozen is used)
2. Installs the environment if needed (unless --no-install is used)
3. Activates the environment
4. Executes the task and any dependencies (unless --skip-deps is used)
5. Returns the exit code of the task

You can use pixi r as a shorthand for pixi run.

Task Dependencies

Tasks can depend on other tasks using the depends-on field. By default, pixi will run all dependencies before the main task. Use --skip-deps to skip this behavior.

Environment Variables

Tasks run in an activated pixi environment with all environment variables set. Use --clean-env to start with a minimal environment.

Template Variables

By default, template variables in command-line arguments are not rendered. Enable this with --templated:

pixi run --templated echo "{{ pixi.platform }}"