Reference (CLI)
Global options#
--verbose (-v|vv|vvv)
Increase the verbosity of the output messages, the -v|vv|vvv increases the level of verbosity respectively.--help (-h)
Shows help information, use-h
to get the short version of the help.--version (-V)
: shows the version of pixi that is used.--quiet (-q)
: Decreases the amount of output.--color <COLOR>
: Whether the log needs to be colored [env:PIXI_COLOR=
] [default:auto
] [possible values: always, never, auto]. Pixi also honor theFORCE_COLOR
andNO_COLOR
environment variables. They both take precedence over--color
andPIXI_COLOR
.
init
#
This command is used to create a new project.
It initializes a pixi.toml
file and also prepares a .gitignore
to prevent the environment from being added to git
.
Arguments#
[PATH]
: Where to place the project (defaults to current path) [default: .]
Options#
--channel <CHANNEL> (-c)
: specify a channel that the project uses. Defaults toconda-forge
. (Allowed to be used more than once)--platform <PLATFORM> (-p)
: specify a platform that the project supports. (Allowed to be used more than once)--import <ENV_FILE> (-i)
: Import an existing conda environment file, e.g.environment.yml
.
Importing an environment.yml
When importing an environment, the pixi.toml
will be created with the dependencies from the environment file.
The pixi.lock
will be created when you install the environment.
We don't support git+
urls as dependencies for pip packages and for the defaults
channel we use main
, r
and msys2
as the default channels.
pixi init myproject
pixi init ~/myproject
pixi init # Initializes directly in the current directory.
pixi init --channel conda-forge --channel bioconda myproject
pixi init --platform osx-64 --platform linux-64 myproject
pixi init --import environment.yml
add
#
Adds dependencies to the pixi.toml
.
It will only add if the package with its version constraint is able to work with rest of the dependencies in the project.
More info on multi-platform configuration.
Arguments#
<SPECS>
: The package(s) to add, space separated. The version constraint is optional.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--host
: Specifies a host dependency, important for building a package.--build
: Specifies a build dependency, important for building a package.--pypi
: Specifies a PyPI dependency, not a conda package. Parses dependencies as PEP508 requirements, supporting extras and versions. See configuration for details.--no-install
: Don't install the package to the environment, only add the package to the lock-file.--no-lockfile-update
: Don't update the lock-file, implies the--no-install
flag.--platform <PLATFORM> (-p)
: The platform for which the dependency should be added. (Allowed to be used more than once)--feature <FEATURE> (-f)
: The feature for which the dependency should be added.
pixi add numpy
pixi add numpy pandas "pytorch>=1.8"
pixi add "numpy>=1.22,<1.24"
pixi add --manifest-path ~/myproject/pixi.toml numpy
pixi add --host "python>=3.9.0"
pixi add --build cmake
pixi add --pypi requests[security]
pixi add --platform osx-64 --build clang
pixi add --no-install numpy
pixi add --no-lockfile-update numpy
pixi add --feature featurex numpy
install
#
Installs all dependencies specified in the lockfile pixi.lock
.
Which gets generated on pixi add
or when you manually change the pixi.toml
file and run pixi install
.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--frozen
: install the environment as defined in the lockfile. Without checking the status of the lockfile. It can also be controlled by thePIXI_FROZEN
environment variable (example:PIXI_FROZEN=true
).--locked
: only install if thepixi.lock
is up-to-date with thepixi.toml
1. It can also be controlled by thePIXI_LOCKED
environment variable (example:PIXI_LOCKED=true
). Conflicts with--frozen
.
pixi install
pixi install --manifest-path ~/myproject/pixi.toml
pixi install --frozen
pixi install --locked
run
#
The run
commands first checks if the environment is ready to use.
When you didn't run pixi install
the run command will do that for you.
The custom tasks defined in the pixi.toml
are also available through the run command.
You cannot run pixi run source setup.bash
as source
is not available in the deno_task_shell
commandos and not an executable.
Arguments#
[TASK]...
The task you want to run in the projects environment, this can also be a normal command. And all arguments after the task will be passed to the task.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--frozen
: install the environment as defined in the lockfile. Without checking the status of the lockfile. It can also be controlled by thePIXI_FROZEN
environment variable (example:PIXI_FROZEN=true
).--locked
: only install if thepixi.lock
is up-to-date with thepixi.toml
1. It can also be controlled by thePIXI_LOCKED
environment variable (example:PIXI_LOCKED=true
). Conflicts with--frozen
.--environment <ENVIRONMENT> (-e)
: The environment to run the task in, if none are provided the default environment will be used or a selector will be given to select the right environment.
pixi run python
pixi run cowpy "Hey pixi user"
pixi run --manifest-path ~/myproject/pixi.toml python
pixi run --frozen python
pixi run --locked python
# If you have specified a custom task in the pixi.toml you can run it with run as well
pixi run build
# Extra arguments will be passed to the tasks command.
pixi run task argument1 argument2
# If you have multiple environments you can select the right one with the --environment flag.
pixi run --environment cuda python
Info
In pixi
the deno_task_shell
is the underlying runner of the run command.
Checkout their documentation for the syntax and available commands.
This is done so that the run commands can be run across all platforms.
Cross environment tasks
If you're using the depends_on
feature of the tasks
, the tasks will be run in the order you specified them.
The depends_on
can be used cross environment, e.g. you have this pixi.toml
:
pixi.toml
Then you're able to run the build
from the build
environment and start
from the default environment.
By only calling:
remove
#
Removes dependencies from the pixi.toml
.
Arguments#
<DEPS>...
: List of dependencies you wish to remove from the project.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--host
: Specifies a host dependency, important for building a package.--build
: Specifies a build dependency, important for building a package.--pypi
: Specifies a PyPI dependency, not a conda package.--platform <PLATFORM> (-p)
: The platform from which the dependency should be removed.--feature <FEATURE> (-f)
: The feature from which the dependency should be removed.
pixi remove numpy
pixi remove numpy pandas pytorch
pixi remove --manifest-path ~/myproject/pixi.toml numpy
pixi remove --host python
pixi remove --build cmake
pixi remove --pypi requests
pixi remove --platform osx-64 --build clang
pixi remove --feature featurex clang
pixi remove --feature featurex --platform osx-64 clang
pixi remove --feature featurex --platform osx-64 --build clang
task
#
If you want to make a shorthand for a specific command you can add a task for it.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.
task add
#
Add a task to the pixi.toml
, use --depends-on
to add tasks you want to run before this task, e.g. build before an execute task.
Arguments#
<NAME>
: The name of the task.<COMMAND>
: The command to run. This can be more than one word.
Info
If you are using $
for env variables they will be resolved before adding them to the task.
If you want to use $
in the task you need to escape it with a \
, e.g. echo \$HOME
.
Options#
--platform <PLATFORM> (-p)
: the platform for which this task should be added.--feature <FEATURE> (-f)
: the feature for which the task is added, if non provided the default tasks will be added.--depends-on <DEPENDS_ON>
: the task it depends on to be run before the one your adding.--cwd <CWD>
: the working directory for the task relative to the root of the project.
pixi task add cow cowpy "Hello User"
pixi task add tls ls --cwd tests
pixi task add test cargo t --depends-on build
pixi task add build-osx "METAL=1 cargo build" --platform osx-64
pixi task add train python train.py --feature cuda
This adds the following to the pixi.toml
:
[tasks]
cow = "cowpy \"Hello User\""
tls = { cmd = "ls", cwd = "tests" }
test = { cmd = "cargo t", depends_on = ["build"] }
[target.osx-64.tasks]
build-osx = "METAL=1 cargo build"
[feature.cuda.tasks]
train = "python train.py"
Which you can then run with the run
command:
task remove
#
Remove the task from the pixi.toml
Arguments#
<NAMES>
: The names of the tasks, space separated.
Options#
--platform <PLATFORM> (-p)
: the platform for which this task is removed.--feature <FEATURE> (-f)
: the feature for which the task is removed.
task alias
#
Create an alias for a task.
Arguments#
<ALIAS>
: The alias name<DEPENDS_ON>
: The names of the tasks you want to execute on this alias, order counts, first one runs first.
Options#
--platform <PLATFORM> (-p)
: the platform for which this alias is created.
pixi task alias test-all test-py test-cpp test-rust
pixi task alias --platform linux-64 test test-linux
pixi task alias moo cow
task list
#
List all tasks in the project.
Options#
--environment
(-e
): the environment's tasks list, if non is provided the default tasks will be listed.--summary
(-s
): the output gets formatted to be machine parsable. (Used in the autocompletion ofpixi run
).
list
#
List project's packages. Highlighted packages are explicit dependencies.
Options#
--platform <PLATFORM> (-p)
: The platform to list packages for. Defaults to the current platform--json
: Whether to output in json format.--json-pretty
: Whether to output in pretty json format--sort-by <SORT_BY>
: Sorting strategy [default: name] [possible values: size, name, type]--manifest-path <MANIFEST_PATH>
: The path topixi.toml
, by default it searches for one in the parent directories.--environment
(-e
): The environment's packages to list, if non is provided the default environment's packages will be listed.--frozen
: Install the environment as defined in the lockfile. Without checking the status of the lockfile. It can also be controlled by thePIXI_FROZEN
environment variable (example:PIXI_FROZEN=true
).--locked
: Only install if thepixi.lock
is up-to-date with thepixi.toml
1. It can also be controlled by thePIXI_LOCKED
environment variable (example:PIXI_LOCKED=true
). Conflicts with--frozen
.--no-install
: Don't install the environment for pypi solving, only update the lock-file if it can solve without installing. (Implied by--frozen
and--locked
)
```shell
pixi list
pixi list --json-pretty
pixi list --sort-by size
pixi list --platform win-64
pixi list --environment cuda
pixi list --frozen
pixi list --locked
pixi list --no-install
python
will be green as it is the package that was explicitly added to the pixi.toml
:
➜ pixi list
Package Version Build Size Kind Source
_libgcc_mutex 0.1 conda_forge 2.5 KiB conda _libgcc_mutex-0.1-conda_forge.tar.bz2
_openmp_mutex 4.5 2_gnu 23.1 KiB conda _openmp_mutex-4.5-2_gnu.tar.bz2
bzip2 1.0.8 hd590300_5 248.3 KiB conda bzip2-1.0.8-hd590300_5.conda
ca-certificates 2023.11.17 hbcca054_0 150.5 KiB conda ca-certificates-2023.11.17-hbcca054_0.conda
ld_impl_linux-64 2.40 h41732ed_0 688.2 KiB conda ld_impl_linux-64-2.40-h41732ed_0.conda
libexpat 2.5.0 hcb278e6_1 76.2 KiB conda libexpat-2.5.0-hcb278e6_1.conda
libffi 3.4.2 h7f98852_5 56.9 KiB conda libffi-3.4.2-h7f98852_5.tar.bz2
libgcc-ng 13.2.0 h807b86a_4 755.7 KiB conda libgcc-ng-13.2.0-h807b86a_4.conda
libgomp 13.2.0 h807b86a_4 412.2 KiB conda libgomp-13.2.0-h807b86a_4.conda
libnsl 2.0.1 hd590300_0 32.6 KiB conda libnsl-2.0.1-hd590300_0.conda
libsqlite 3.44.2 h2797004_0 826 KiB conda libsqlite-3.44.2-h2797004_0.conda
libuuid 2.38.1 h0b41bf4_0 32.8 KiB conda libuuid-2.38.1-h0b41bf4_0.conda
libxcrypt 4.4.36 hd590300_1 98 KiB conda libxcrypt-4.4.36-hd590300_1.conda
libzlib 1.2.13 hd590300_5 60.1 KiB conda libzlib-1.2.13-hd590300_5.conda
ncurses 6.4 h59595ed_2 863.7 KiB conda ncurses-6.4-h59595ed_2.conda
openssl 3.2.0 hd590300_1 2.7 MiB conda openssl-3.2.0-hd590300_1.conda
python 3.12.1 hab00c5b_1_cpython 30.8 MiB conda python-3.12.1-hab00c5b_1_cpython.conda
readline 8.2 h8228510_1 274.9 KiB conda readline-8.2-h8228510_1.conda
tk 8.6.13 noxft_h4845f30_101 3.2 MiB conda tk-8.6.13-noxft_h4845f30_101.conda
tzdata 2023d h0c530f3_0 116.8 KiB conda tzdata-2023d-h0c530f3_0.conda
xz 5.2.6 h166bdaf_0 408.6 KiB conda xz-5.2.6-h166bdaf_0.tar.bz2
shell
#
This command starts a new shell in the project's environment.
To exit the pixi shell, simply run exit
.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--frozen
: install the environment as defined in the lockfile. Without checking the status of the lockfile. It can also be controlled by thePIXI_FROZEN
environment variable (example:PIXI_FROZEN=true
).--locked
: only install if thepixi.lock
is up-to-date with thepixi.toml
1. It can also be controlled by thePIXI_LOCKED
environment variable (example:PIXI_LOCKED=true
). Conflicts with--frozen
.--environment <ENVIRONMENT> (-e)
: The environment to activate the shell in, if none are provided the default environment will be used or a selector will be given to select the right environment.
pixi shell
exit
pixi shell --manifest-path ~/myproject/pixi.toml
exit
pixi shell --frozen
exit
pixi shell --locked
exit
pixi shell --environment cuda
exit
shell-hook
#
This command prints the activation script of an environment.
Options#
--shell <SHELL> (-s)
: The shell for which the activation script should be printed. Defaults to the current shell. Currently supported variants: [bash
,zsh
,xonsh
,cmd
,powershell
,fish
,nushell
]--manifest-path
: the path topixi.toml
, by default it searches for one in the parent directories.--frozen
: install the environment as defined in the lockfile. Without checking the status of the lockfile. It can also be controlled by thePIXI_FROZEN
environment variable (example:PIXI_FROZEN=true
).--locked
: only install if thepixi.lock
is up-to-date with thepixi.toml
1. It can also be controlled by thePIXI_LOCKED
environment variable (example:PIXI_LOCKED=true
). Conflicts with--frozen
.--environment <ENVIRONMENT> (-e)
: The environment to activate, if none are provided the default environment will be used or a selector will be given to select the right environment.
pixi shell-hook
pixi shell-hook --shell bash
pixi shell-hook --shell zsh
pixi shell-hook -s powershell
pixi shell-hook --manifest-path ~/myproject/pixi.toml
pixi shell-hook --frozen
pixi shell-hook --locked
pixi shell-hook --environment cuda
pixi
executable in a Docker container.
pixi shell-hook --shell bash > /etc/profile.d/pixi.sh
rm ~/.pixi/bin/pixi # Now the environment will be activated without the need for the pixi executable.
search
#
Search a package, output will list the latest version of the package.
Arguments#
<PACKAGE>
: Name of package to search, it's possible to use wildcards (*
).
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--channel <CHANNEL> (-c)
: specify a channel that the project uses. Defaults toconda-forge
. (Allowed to be used more than once)--limit <LIMIT> (-l)
: Limit the number of search results (default: 15)
self-update
#
Update pixi to the latest version or a specific version. If the pixi binary is not found in the default location (e.g.
~/.pixi/bin/pixi
), pixi won't update to prevent breaking the current installation (Homebrew, etc.). The behaviour can be
overridden with the --force
flag
Options#
--version <VERSION>
: The desired version (to downgrade or upgrade to). Update to the latest version if not specified.--force
: Force the update even if the pixi binary is not found in the default location.
info
#
Shows helpful information about the pixi installation, cache directories, disk usage, and more. More information here.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.--extended
: extend the information with more slow queries to the system, like directory sizes.--json
: Get a machine-readable version of the information as output.
upload
#
Upload a package to a prefix.dev channel
Arguments#
<HOST>
: The host + channel to upload to.<PACKAGE_FILE>
: The package file to upload.
auth
#
This command is used to authenticate the user's access to remote hosts such as prefix.dev
or anaconda.org
for private channels.
auth login
#
Store authentication information for given host.
Tip
The host is real hostname not a channel.
Arguments#
<HOST>
: The host to authenticate with.
Options#
--token <TOKEN>
: The token to use for authentication with prefix.dev.--username <USERNAME>
: The username to use for basic HTTP authentication--password <PASSWORD>
: The password to use for basic HTTP authentication.--conda-token <CONDA_TOKEN>
: The token to use onanaconda.org
/quetz
authentication.
pixi auth login repo.prefix.dev --token pfx_JQEV-m_2bdz-D8NSyRSaNdHANx0qHjq7f2iD
pixi auth login anaconda.org --conda-token ABCDEFGHIJKLMNOP
pixi auth login https://myquetz.server --user john --password xxxxxx
auth logout
#
Remove authentication information for a given host.
Arguments#
<HOST>
: The host to authenticate with.
global
#
Global is the main entry point for the part of pixi that executes on the global(system) level.
Tip
Binaries and environments installed globally are stored in ~/.pixi
by default, this can be changed by setting the PIXI_HOME
environment
variable.
global install
#
This command installs a package into its own environment and adds the binary to PATH
, allowing you to access it anywhere on your system without activating the environment.
Arguments#
1.<PACKAGE>
: The package to install, this can also be a version constraint.
Options#
--channel <CHANNEL> (-c)
: specify a channel that the project uses. Defaults toconda-forge
. (Allowed to be used more than once)
pixi global install ruff
pixi global install starship
pixi global install --channel conda-forge --channel bioconda trackplot
# Or in a more concise form
pixi global install -c conda-forge -c bioconda trackplot
# Support full conda matchspec
pixi global install python=3.9.*
pixi global install "python [version='3.11.0', build_number=1]"
pixi global install "python [version='3.11.0', build=he550d4f_1_cpython]"
pixi global install python=3.11.0=h10a6764_1_cpython
After using global install, you can use the package you installed anywhere on your system.
global list
#
This command shows the current installed global environments including what binaries come with it. A global installed package/environment can possibly contain multiple binaries. Here is an example of a few installed packages:
> pixi global list
Globally installed binary packages:
- [package] starship
- [bin] starship
- [package] pre-commit
- [bin] pre-commit
- [package] grayskull
- [bin] grayskull
- [bin] greyskull
- [bin] conda-grayskull
- [bin] conda-greyskull
- [package] zsh
- [bin] zsh
- [bin] zsh-5
global upgrade
#
This command upgrades a globally installed package to the latest version.
Arguments#
<PACKAGE>
: The package to upgrade.
Options#
--channel <CHANNEL> (-c)
: specify a channel that the project uses. Defaults toconda-forge
. (Allowed to be used more than once)
pixi global upgrade ruff
pixi global upgrade --channel conda-forge --channel bioconda trackplot
# Or in a more concise form
pixi global upgrade -c conda-forge -c bioconda trackplot
global upgrade-all
#
This command upgrades all globally installed packages to their latest version.
Options#
--channel <CHANNEL> (-c)
: specify a channel that the project uses. Defaults toconda-forge
. (Allowed to be used more than once)
pixi global upgrade-all
pixi global upgrade-all --channel conda-forge --channel bioconda
# Or in a more concise form
pixi global upgrade-all -c conda-forge -c bioconda trackplot
global remove
#
Removes a package previously installed into a globally accessible location via
pixi global install
Use pixi global info
to find out what the package name is that belongs to the tool you want to remove.
Arguments#
<PACKAGE>
: The package to remove.
project
#
This subcommand allows you to modify the project configuration through the command line interface.
Options#
--manifest-path <MANIFEST_PATH>
: the path topixi.toml
, by default it searches for one in the parent directories.
project channel add
#
Add channels to the channel list in the project configuration. When you add channels, the channels are tested for existence, added to the lockfile and the environment is reinstalled.
Arguments#
<CHANNEL>
: The channels to add, name or URL.
Options#
--no-install
: do not update the environment, only add changed packages to the lock-file.--feature <FEATURE> (-f)
: The feature for which the channel is added.
pixi project channel add robostack
pixi project channel add bioconda conda-forge robostack
pixi project channel add file:///home/user/local_channel
pixi project channel add https://repo.prefix.dev/conda-forge
pixi project channel add --no-install robostack
pixi project channel add --feature cuda nividia
project channel list
#
List the channels in the project file
Options#
urls
: show the urls of the channels instead of the names.
$ pixi project channel list
Environment: default
- conda-forge
$ pixi project channel list --urls
Environment: default
- https://conda.anaconda.org/conda-forge/
project channel remove
#
List the channels in the project file
Arguments#
<CHANNEL>...
: The channels to remove, name(s) or URL(s).
Options#
--no-install
: do not update the environment, only add changed packages to the lock-file.--feature <FEATURE> (-f)
: The feature for which the channel is removed.
pixi project channel remove conda-forge
pixi project channel remove https://conda.anaconda.org/conda-forge/
pixi project channel remove --no-install conda-forge
pixi project channel remove --feature cuda nividia
project description get
#
Get the project description.
project description set
#
Set the project description.
Arguments#
<DESCRIPTION>
: The description to set.
project platform add
#
Adds a platform(s) to the project file and updates the lockfile.
Arguments#
<PLATFORM>...
: The platforms to add.
Options#
--no-install
: do not update the environment, only add changed packages to the lock-file.--feature <FEATURE> (-f)
: The feature for which the platform will be added.
project platform list
#
List the platforms in the project file.
project platform remove
#
Remove platform(s) from the project file and updates the lockfile.
Arguments#
<PLATFORM>...
: The platforms to remove.
Options#
--no-install
: do not update the environment, only add changed packages to the lock-file.--feature <FEATURE> (-f)
: The feature for which the platform will be removed.
project version get
#
Get the project version.
project version set
#
Set the project version.
Arguments#
<VERSION>
: The version to set.
project version {major|minor|patch}
#
Bump the project version to {MAJOR|MINOR|PATCH}.
-
An up-to-date lockfile means that the dependencies in the lockfile are allowed by the dependencies in the manifest file. For example
- a
pixi.toml
withpython = ">= 3.11"
is up-to-date with aname: python, version: 3.11.0
in thepixi.lock
. - a
pixi.toml
withpython = ">= 3.12"
is not up-to-date with aname: python, version: 3.11.0
in thepixi.lock
.
Being up-to-date does not mean that the lockfile holds the latest version available on the channel for the given dependency. ↩↩↩↩↩
- a