Pixi Global#
With pixi global
, users can manage globally installed tools in a way that makes them available from any directory.
This means that the pixi environment will be placed in a global location, and the tools will be exposed to the system PATH
, allowing you to run them from the command line.
Basic Usage#
Running the following command installs rattler-build
on your system.
What's great about pixi global
is that, by default, it isolates each package in its own environment, exposing only the necessary entry points.
This means you don't have to worry about removing a package and accidentally breaking seemingly unrelated packages.
This behavior is quite similar to that of pipx
.
However, there are times when you may want multiple dependencies in the same environment.
For instance, while ipython
is really useful on its own, it becomes much more useful when numpy
and matplotlib
are available when using it.
Let's execute the following command:
numpy
exposes executables, but since it's added via --with
it's executables are not being exposed.
Importing numpy
and matplotlib
now works as expected.
At some point, you might want to install multiple versions of the same package on your system.
Since they will be all available on the system PATH
, they need to be exposed under different names.
Let's check out the following command:
By specifying --expose
we specified that we want to expose the executable python
under the name py3
.
The package python
has more executables, but since we specified --exposed
they are not auto-exposed.
You can run py3
to start the python interpreter.
The Global Manifest#
Since v0.33.0
pixi has a new manifest file that will be created in the global directory.
This file will contain the list of environments that are installed globally, their dependencies and exposed binaries.
The manifest can be edited, synced, checked in to a version control system, and shared with others.
Running the commands from the section before results in the following manifest:
version = 1
[envs.rattler-build]
channels = ["conda-forge"]
dependencies = { rattler-build = "*" }
exposed = { rattler-build = "rattler-build" }
[envs.ipython]
channels = ["conda-forge"]
dependencies = { ipython = "*", numpy = "*", matplotlib = "*" }
exposed = { ipython = "ipython", ipython3 = "ipython3" }
[envs.python]
channels = ["conda-forge"]
dependencies = { python = "3.12.*" } # (1)!
exposed = { py3 = "python" } # (2)!
- Dependencies are the packages that will be installed in the environment. You can specify the version or use a wildcard.
- The exposed binaries are the ones that will be available in the system path. In this case,
python
is exposed under the namepy3
.
Manifest locations#
The manifest can be found at the following locations depending on your operating system.
Priority | Location | Comments |
---|---|---|
1 | $HOME/.pixi/manifests/pixi-global.toml |
User-specific manifest |
2 | $PIXI_HOME/manifests/pixi-global.toml |
Global manifest in the user home directory. PIXI_HOME defaults to ~/.pixi |
Priority | Location | Comments |
---|---|---|
1 | $HOME/.pixi/manifests/pixi-global.toml |
User-specific manifest |
2 | $PIXI_HOME/manifests/pixi-global.toml |
Global manifest in the user home directory. PIXI_HOME defaults to ~/.pixi |
Priority | Location | Comments |
---|---|---|
1 | %USERPROFILE%\.pixi\manifests\pixi-global.toml |
User-specific manifest |
2 | $PIXI_HOME\manifests/pixi-global.toml |
Global manifest in the user home directory. PIXI_HOME defaults to %USERPROFILE%/.pixi |
Note
If multiple locations exist, the manifest with the highest priority will be used.
Channels#
The channels are the conda channels that will be used to search for the packages. There is a priority to these, so the first one will have the highest priority, if a package is not found in that channel the next one will be used. For example, running:
Results in the following entry in the manifest:[envs.snakemake]
channels = ["conda-forge", "bioconda"]
dependencies = { snakemake = "*" }
exposed = { snakemake = "snakemake" }
More information on channels can be found here.
Automatic Exposed#
There is some added automatic behavior, if you install a package with the same name as the environment, it will be exposed with the same name. Even if the binary name is only exposed through dependencies of the package For example, running:
will create the following entry in the manifest:[envs.ansible]
channels = ["conda-forge"]
dependencies = { ansible = "*" }
exposed = { ansible = "ansible" } # (1)!
- The
ansible
binary is exposed even though it is installed by a dependency ofansible
, theansible-core
package.
Dependencies#
Dependencies are the Conda packages that will be installed into your environment. For example, running:
creates the following entry in the manifest: Typically, you'd specify just the tool you're installing, but you can add more packages if needed. Defining the environment to install into will allow you to add multiple dependencies at once. For example, running: will create the following entry in the manifest:[envs.my-env]
channels = ["conda-forge"]
dependencies = { git = "*", vim = "*", python = "*" }
# ...
You can add
a dependency to an existing environment by running:
my-env
environment but won't auto expose the binaries from the new packages.
You can remove
dependencies by running:
Trampolines#
To increase efficiency, pixi
uses trampolines—small, specialized binary files that manage configuration and environment setup before executing the main binary. The trampoline approach allows for skipping the execution of activation scripts that have a significant performance impact.
When you execute a global install binary, a trampoline performs the following sequence of steps:
- Each trampoline first reads a configuration file named after the binary being executed. This configuration file, in JSON format (e.g.,
python.json
), contains key information about how the environment should be set up. The configuration file is stored in.pixi/bin/trampoline_configuration
. - Once the configuration is loaded and the environment is set, the trampoline executes the original binary with the correct environment settings.
- When installing a new binary, a new trampoline is placed in the
.pixi/bin
directory and is hard-linked to the.pixi/bin/trampoline_configuration/trampoline_bin
. This optimizes storage space and avoids duplication of the same trampoline.
Example: Adding a series of tools at once#
Without specifying an environment, you can add multiple tools at once:
This command generates the following entry in the manifest:[envs.pixi-pack]
channels = ["conda-forge"]
dependencies= { pixi-pack = "*" }
exposed = { pixi-pack = "pixi-pack" }
[envs.rattler-build]
channels = ["conda-forge"]
dependencies = { rattler-build = "*" }
exposed = { rattler-build = "rattler-build" }
Example: Creating a Data Science Sandbox Environment#
You can create an environment with multiple tools using the following command:
pixi global install --environment data-science --expose jupyter --expose ipython jupyter numpy pandas matplotlib ipython
[envs.data-science]
channels = ["conda-forge"]
dependencies = { jupyter = "*", ipython = "*" }
exposed = { jupyter = "jupyter", ipython = "ipython" }
jupyter
and ipython
are exposed from the data-science
environment, allowing you to run:
These commands will be available globally, making it easy to access your preferred tools without switching environments.
Example: Install packages for a different platform#
You can install packages for a different platform using the --platform
flag.
This is useful when you want to install packages for a different platform, such as osx-64
packages on osx-arm64
.
For example, running this on osx-arm64
:
[envs.python]
channels = ["conda-forge"]
platforms = ["osx-64"]
dependencies = { python = "*" }
# ...
Potential Future Features#
PyPI support#
We could support packages from PyPI via a command like this:
Lock file#
A lock file is less important for global tools. However, there is demand for it, and users that don't care about it should not be negatively impacted
Multiple manifests#
We could go for one default manifest, but also parse other manifests in the same directory.
The only requirement to be parsed as manifest is a .toml
extension
In order to modify those with the CLI
one would have to add an option --manifest
to select the correct one.
- pixi-global.toml: Default
- pixi-global-company-tools.toml
- pixi-global-from-my-dotfiles.toml
It is unclear whether the first implementation already needs to support this.
At the very least we should put the manifest into its own folder like ~/.pixi/global/manifests/pixi-global.toml
No activation#
The current pixi global install
features --no-activation
.
When this flag is set, CONDA_PREFIX
and PATH
will not be set when running the exposed executable.
This is useful when installing Python package managers or shells.
Assuming that this needs to be set per mapping, one way to expose this functionality would be to allow the following: