diff --git a/docs/advanced/override.md b/docs/advanced/override.md index bd22cc6f6d..adcf0e8b16 100644 --- a/docs/advanced/override.md +++ b/docs/advanced/override.md @@ -30,7 +30,8 @@ numpy = ">=2.0.0" This will override the version of `numpy` used by all dependencies in the `dev` feature to be at least `2.0.0`, regardless of what the dependencies specify when the `dev` feature is enabled. ### Interact with other overrides -For a specific environment, all the `dependency-overrides` defined in different features will be combined in the order they were when defining the environment. + +For a specific environment, all the `dependency-overrides` defined in different features will be combined in the order they were defined. If the same dependency is overridden multiple times, we'll use the override from the **prior** feature in that environment. @@ -63,4 +64,6 @@ outdated: `numpy == 1.21.0` conflict_a: `numpy == 1.21.0` (from `outdated`) conflict_b: `numpy == 2.0.0` (from `dev`) -This may contrast with the intuition that all overrides are applied and combined to a result, but it is done this way to avoid conflicts and confusion. Since users are granted fully control over the overrides, it is up to ourselves to choose the right overrides for the environment. +This may contrast with the intuition that all overrides are applied and combined to a result. It +is done this way to avoid conflicts and confusion: Since users are granted fully control over the +overrides, it is up to them to choose the right overrides for an environment. diff --git a/docs/advanced/pixi_shell.md b/docs/advanced/pixi_shell.md index 1ab4983a49..e36f9e1186 100644 --- a/docs/advanced/pixi_shell.md +++ b/docs/advanced/pixi_shell.md @@ -6,13 +6,20 @@ That also means that, instead of `conda deactivate`, it's enough to just exit th pixi shell ``` -On Unix systems the shell command works by creating a "fake" PTY session that will start the shell, and then send a string like `source /tmp/activation-env-12345.sh` to the `stdin` in order to activate the environment. If you would peek under the hood of the the `shell` command, then you would see that this is the first thing executed in the new shell session. +On Unix systems the shell command works by creating a "fake" PTY session that will start the shell, +and then send a string like `source /tmp/activation-env-12345.sh` to the `stdin` in order to activate +the environment. If you would peek under the hood of the the `shell` command, then you +would see that this is the first thing executed in the new shell session. -The temporary script that we generate ends with `echo "PIXI_ENV_ACTIVATED"` which is used to detect if the environment was activated successfully. If we do not receive this string after three seconds, we will issue a warning to the user. +The temporary script that we generate ends with `echo "PIXI_ENV_ACTIVATED"` which is used to detect +if the environment was activated successfully. If we do not receive this string after +three seconds, we will issue a warning to the user. ## Issues With Pixi Shell -As explained, `pixi shell` only works well if we execute the activation script _after_ launching shell. Certain commands that are run in the `~/.bashrc` might swallow the activation command, and the environment won't be activated. +As explained, `pixi shell` only works well if we execute the activation script _after_ launching shell. +Certain commands that are run in the `~/.bashrc` might swallow the activation command, and the +environment won't be activated. For example, if your `~/.bashrc` contains code like the following, `pixi shell` has little chance to succeed: diff --git a/docs/advanced/shebang.md b/docs/advanced/shebang.md index 214245fdbb..0f79754759 100644 --- a/docs/advanced/shebang.md +++ b/docs/advanced/shebang.md @@ -1,8 +1,10 @@ !!!warning "Only on Unix-like systems" The following approach only works on Unix-like systems (i.e. Linux and macOS) since Windows does not support shebang lines. -For simple scripts, you can use [`pixi exec`](../reference/cli/pixi/exec.md) to run them directly without needing to take care of installing dependencies or setting up an environment. -This can be done by adding a [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top of the script, which tells the system how to execute the script. +For simple scripts, you can use [`pixi exec`](../reference/cli/pixi/exec.md) to run them directly +without needing to take care of installing dependencies or setting up an environment. +This can be done by adding a [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top +of the script, which tells the system how to execute the script. Usually, a shebang line starts with `#!/usr/bin/env` followed by the name of the interpreter to use. Instead of adding an interpreter, you can also just add `pixi exec` at the beginning of the script. diff --git a/docs/build/dependency_types.md b/docs/build/dependency_types.md index 62d08f7149..17e8dbef58 100644 --- a/docs/build/dependency_types.md +++ b/docs/build/dependency_types.md @@ -1,4 +1,5 @@ -If you add a package to the [dependency table](../reference/pixi_manifest.md#dependencies) of a feature that dependency will be available in all environments that include that feature. +If you add a package to the [dependency table](../reference/pixi_manifest.md#dependencies) of a feature +that dependency will be available in all environments that include that feature. The dependencies of a package that is being built are a bit more granular. Here you can see the three types of dependencies for a simple C++ package. diff --git a/docs/build/dev.md b/docs/build/dev.md index 39b4ad8612..413612a844 100644 --- a/docs/build/dev.md +++ b/docs/build/dev.md @@ -1,7 +1,7 @@ The source packages in the `[dev]` table are not built or installed into the pixi environment. The `build-dependencies`, `host-dependencies` and `run-dependencies` of those packages are installed into the pixi environment. -Source dependencies in the `[dependencies]` section are build in an isolated environment and then installed into the workspace. +Source dependencies in the `[dependencies]` section are build in their own isolated environment located at`.pixi/build` and the resulting conda package is then installed into the default environment. This means that the `build-` and `host-dependencies` will not be in the pixi environment. This document explains how you can use the `[dev]` table to depend on the development dependencies of a package. @@ -10,24 +10,26 @@ This document explains how you can use the `[dev]` table to depend on the develo Assume a Rust package that you want to develop using Pixi. Then we add a `pixi.toml` manifest file: + ```toml title="pixi.toml" --8<-- "docs/source_files/pixi_workspaces/pixi_build/dev/pixi.toml:minimal" ``` + Now you can use Pixi to build the package into a conda package: ```bash pixi build ``` -But because of the isolated build environments, the development dependencies such as `cargo` are not available in `pixi run`. +Because of the isolation, the development dependencies such as `cargo` are not available in `pixi run`. -To change that you can add `[dev]` table to the manifest file: +To change that you can add a `[dev]` table to the manifest file: ```toml title="pixi.toml" --8<-- "docs/source_files/pixi_workspaces/pixi_build/dev/pixi.toml:dev" ``` -Now when you run `pixi install` the development dependencies will be installed into the pixi environment. +Now when you run `pixi install` the development dependencies will be installed into the Pixi environment. This means that you can now use `cargo` in `pixi run`: ```bash @@ -39,6 +41,7 @@ Thus, you can use them during development. ## Extended example This is a full `pixi.toml` example using the `[dev]` table: + ```toml title="pixi.toml" --8<-- "docs/source_files/pixi_workspaces/pixi_build/dev/pixi.toml" ``` diff --git a/docs/concepts/conda_pypi.md b/docs/concepts/conda_pypi.md index 4bf367138a..a520043b8b 100644 --- a/docs/concepts/conda_pypi.md +++ b/docs/concepts/conda_pypi.md @@ -19,6 +19,7 @@ The simplified process is as follows: ## Tool Comparison + Here is a non-exhaustive comparison of the features of conda and PyPI ecosystems. | Feature | Conda | PyPI | diff --git a/docs/deployment/pixi_pack.md b/docs/deployment/pixi_pack.md index e5117a79c9..d941d0eded 100644 --- a/docs/deployment/pixi_pack.md +++ b/docs/deployment/pixi_pack.md @@ -1,6 +1,8 @@ -[`pixi-pack`](https://github.com/quantco/pixi-pack) is a simple tool that takes a Pixi environment and packs it into a compressed archive that can be shipped to the target machine. The corresponding `pixi-unpack` tool can be used to unpack the archive and install the environment. +[`pixi-pack`](https://github.com/quantco/pixi-pack) is a simple tool that takes an environment +and packs it into a compressed archive that can be shipped to the target machine. The corresponding +`pixi-unpack` tool can be used to unpack the archive and recreate an environment. Both tools can be installed via @@ -140,7 +142,8 @@ You can inject additional packages into the environment that are not specified i pixi-pack --inject local-package-1.0.0-hbefa133_0.conda pixi.toml ``` -This can be particularly useful if you build the package itself and want to include the built package in the environment but still want to use `pixi.lock` from the workspace. +This can be particularly useful if you build the package itself and want to include the built package +in the environment but still want to use `pixi.lock` from the workspace. ### PyPi support @@ -202,7 +205,7 @@ Using a cache is particularly useful when: - Creating multiple packs with overlapping dependencies - Working with large packages that take time to download -- Operating in environments with limited bandwidth +- Operating on machines with limited bandwidth - Running CI/CD pipelines where package caching can significantly improve build times ### Unpacking Without pixi-pack diff --git a/docs/first_workspace.md b/docs/first_workspace.md index a8933e6d57..2b797f90d1 100644 --- a/docs/first_workspace.md +++ b/docs/first_workspace.md @@ -1,10 +1,12 @@ # Making a Pixi workspace Pixi's biggest strength is its ability to create reproducible, powerful, and flexible workspaces. -A workspace lives in a directory on your system, and is a collection of Pixi environments that can be used to develop one or many projects in that directory. -Let's go over the common steps to create a simple Pixi workspace. +A workspace lives in a directory on your system, and is a collection of environments +that can be used to develop one or many projects in that directory. Let's go over the common steps +to create a simple Pixi workspace. ## Creating a Pixi workspace + To create a new Pixi workspace, you can use the `pixi init` command: ```shell @@ -44,10 +46,13 @@ version = "0.1.0" Or use the integrated schema support in PyCharm. ## Managing dependencies + After creating the workspace, you can start adding dependencies. Pixi uses the `pixi add` command to add dependencies to a workspace. -This command will, by default, add the [**conda**](https://prefix.dev/blog/what-is-a-conda-package) dependency to the `pixi.toml`, solve the dependencies, write the [lock file](./workspace/lockfile.md), and install the package in the environment. -For example, let's add `numpy` and `pytest` to the workspace. +This command will, by default, add the [**conda**](https://prefix.dev/blog/what-is-a-conda-package) +dependency to the `pixi.toml`, solve the dependencies, write the [lock file](./workspace/lockfile.md), +and install the package into an environment. For example, let's add `numpy` and `pytest` +to the workspace. ```shell pixi add numpy pytest @@ -85,6 +90,7 @@ httpx = ">=0.28.1,<0.29" To learn more about the differences between `conda` and PyPI, see [our Conda & PyPI concept documentation](./concepts/conda_pypi.md). ## Lock file + Pixi will always create a lock file when the dependencies are solved. This file will contain all the exact versions of the workspace's dependencies (and their dependencies). This results in a reproducible environment, which you can share with others, and use for testing and deployment. @@ -118,6 +124,7 @@ packages: ``` ## Managing tasks + Pixi has a built-in cross-platform task runner which allows you to define tasks in the manifest. Think of tasks as commands (or chains of commands) which you may want to repeat many times over the course of developing a project (for example, running the tests). @@ -140,6 +147,7 @@ You can then run the task using the `pixi run` command: ```shell pixi run hello ``` + This will execute the command `echo Hello, World!` in the workspace's default environment. ??? tip "Do you want to use more powerful features?" @@ -169,13 +177,18 @@ This will execute the command `echo Hello, World!` in the workspace's default en More information about tasks can be found in the [Tasks](./workspace/advanced_tasks.md) section of the documentation. ## Environments + Pixi always creates an environment for your workspace (the "default" environment), which contains your `dependencies` and in which your tasks are run. You can also include [multiple environments](./workspace/multi_environment.md) in one workspace. -These environments are [located](./reference/pixi_configuration.md#detached-environments "Find out how to move this location if required") in the `.pixi/envs` directory in the root of your workspace. +These environments are [located](./reference/pixi_configuration.md#detached-environments "Find out how to move this location if required") +in the `.pixi/envs` directory in the root of your workspace. Using these environments is as simple as running the `pixi run` or `pixi shell` command. -`pixi run` will execute the remaining input as a command (or a task if the input matches the name of a defined task) in the environment, while `pixi shell` will spawn a new shell session in the environment. Both commands "activate" the environment — learn more at [our environment activation documentation](./workspace/environment.md#activation). +`pixi run` will execute the remaining input as a command (or a task if the input matches the name of a defined task) +in the environment, while `pixi shell` will spawn a new shell session in the environment. +Both commands "activate" the environment — learn more at +[our environment activation documentation](./workspace/environment.md#activation). ```shell pixi run python -VV diff --git a/docs/getting_started.md b/docs/getting_started.md index fb30640784..f9863530f7 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -19,20 +19,22 @@ Let's go through the basic usage of Pixi. - [`pixi clean`](./reference/cli/pixi/clean.md) - remove the environment from your machine ## Managing global installations -Pixi can manage global installations of tools and environments. + +Pixi can manage global installations of tools in global environments. It installs the environments in a central location, so you can use them from anywhere. - [`pixi global install`](./reference/cli/pixi/global/install.md) - install a package into it's own environment in the global space. - [`pixi global uninstall`](./reference/cli/pixi/global/uninstall.md) - uninstall an environment from the global space. -- [`pixi global add`](./reference/cli/pixi/global/add.md) - add a package to an existing globally installed environment. +- [`pixi global add`](./reference/cli/pixi/global/add.md) - add a package to an existing global environment. - [`pixi global sync`](./reference/cli/pixi/global/sync.md) - sync the globally installed environments with the global manifest, describing all the environments you want to install. - [`pixi global edit`](./reference/cli/pixi/global/edit.md) - edit the global manifest. - [`pixi global update`](./reference/cli/pixi/global/update.md) - update the global environments -- [`pixi global list`](./reference/cli/pixi/global/list.md) - list all the installed environments +- [`pixi global list`](./reference/cli/pixi/global/list.md) - list all the global environments More information: [Global Tools](./global_tools/introduction.md) ## Running one-off commands + Pixi can run one-off commands in a specific environment. - [`pixi exec`](./reference/cli/pixi/exec.md) - run a command in a temporary environment. @@ -47,9 +49,9 @@ Python 3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:24:05) [Clang 1 Python 3.12.11 | packaged by conda-forge | (main, Jun 4 2025, 14:38:53) [Clang 18.1.8 ] ``` -## Multiple environments -Pixi workspaces allow you to manage multiple environments. -An environment is build out of one or multiple features. +## Multiple Environments + +Pixi workspaces allow you to manage multiple environments. An environment is build out of one or multiple features. - [`pixi add --feature`](./reference/cli/pixi/add.md#arg---feature) - add a package to a feature - [`pixi task add --feature`](./reference/cli/pixi/task/add.md#arg---feature) - add a task to a specific feature @@ -58,9 +60,10 @@ An environment is build out of one or multiple features. - [`pixi shell --environment`](./reference/cli/pixi/shell.md#arg---environment) - activate a specific environment - [`pixi list --environment`](./reference/cli/pixi/list.md#arg---environment) - list the dependencies in a specific environment -More information: [Multiple environments](./workspace/multi_environment.md) +More information: [Multiple Environments](./workspace/multi_environment.md) ## Tasks + Pixi can run cross-platform tasks using it's built-in task runner. This can be a predefined task or any normal executable. @@ -69,6 +72,7 @@ This can be a predefined task or any normal executable. Tasks can have other tasks as dependencies. Here is an example of a more complex task use case + ```toml title="pixi.toml" [tasks] build = "make build" @@ -77,9 +81,11 @@ build = "make build" cmd = "pytest" depends-on = ["build"] ``` + More information: [Tasks](./workspace/advanced_tasks.md) ## Multi platform support + Pixi supports multiple platforms out of the box. You can specify which platforms your workspace supports and Pixi will ensure that the dependencies are compatible with those platforms. @@ -89,6 +95,7 @@ You can specify which platforms your workspace supports and Pixi will ensure tha More information: [Multi platform support](./workspace/multi_platform_configuration.md) ## Utilities + Pixi comes with a set of utilities to help you debug or manage your setup. - [`pixi info`](./reference/cli/pixi/info.md) - Show information about the current workspace, and the global setup. diff --git a/docs/global_tools/introduction.md b/docs/global_tools/introduction.md index b396a3ed78..334c40126b 100644 --- a/docs/global_tools/introduction.md +++ b/docs/global_tools/introduction.md @@ -178,11 +178,14 @@ end ## Adding a Series of Tools at Once -Without specifying an environment, you can add multiple tools at once: +Without specifying an inastallation environment, you can add multiple tools at once: + ```shell pixi global install pixi-pack rattler-build ``` + This command generates the following entry in the manifest: + ```toml [envs.pixi-pack] channels = ["conda-forge"] @@ -194,27 +197,34 @@ channels = ["conda-forge"] dependencies = { rattler-build = "*" } exposed = { rattler-build = "rattler-build" } ``` + Creating two separate non-interfering environments, while exposing only the minimum required binaries. ## Creating a Data Science Sandbox Environment You can create an environment with multiple tools using the following command: + ```shell pixi global install --environment data-science --expose jupyter --expose ipython jupyter numpy pandas matplotlib ipython ``` + This command generates the following entry in the manifest: + ```toml [envs.data-science] channels = ["conda-forge"] dependencies = { jupyter = "*", ipython = "*" } exposed = { jupyter = "jupyter", ipython = "ipython" } ``` + In this setup, both `jupyter` and `ipython` are exposed from the `data-science` environment, allowing you to run: + ```shell > ipython # Or > jupyter lab ``` + These commands will be available globally, making it easy to access your preferred tools without switching environments. ## Install Packages For a Different Platform diff --git a/docs/global_tools/manifest.md b/docs/global_tools/manifest.md index 2991cb3b69..2ab2751d6b 100644 --- a/docs/global_tools/manifest.md +++ b/docs/global_tools/manifest.md @@ -23,7 +23,7 @@ dependencies = { python = "3.12.*" } # (1)! exposed = { py3 = "python" } # (2)! ``` -1. Dependencies are the packages that will be installed in the environment. You can specify the version or use a wildcard. +1. Dependencies are the packages that will be installed into the environment. You can specify the version or use a wildcard. 2. The exposed binaries are the ones that will be available in the system path. In this case, `python` is exposed under the name `py3`. ## Manifest locations diff --git a/docs/global_tools/trampolines.md b/docs/global_tools/trampolines.md index 099b42f0b6..a5cf7bac8a 100644 --- a/docs/global_tools/trampolines.md +++ b/docs/global_tools/trampolines.md @@ -1,12 +1,19 @@ ## 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. +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 globally installed executable, 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_HOME`](../reference/environment_variables.md)`/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_HOME`](../reference/environment_variables.md)`/bin` directory and is hard-linked to the [`$PIXI_HOME`](../reference/environment_variables.md)`/bin/trampoline_configuration/trampoline_bin`. This optimizes storage space and avoids duplication of the same trampoline. +* 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_HOME`](../reference/environment_variables.md)`/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_HOME`](../reference/environment_variables.md)`/bin` + directory and is hard-linked to the [`$PIXI_HOME`](../reference/environment_variables.md)`/bin/trampoline_configuration/trampoline_bin`. + This optimizes storage space and avoids duplication of the same trampoline. The trampoline will take care that the `PATH` contains the newest changes on your local `PATH` while avoiding caching temporary `PATH` changes during installation. If you want to control the base `PATH` pixi considers, you can set `export PIXI_BASE_PATH=$PATH` in your shell startup script. diff --git a/docs/index.md b/docs/index.md index 5b8416b3ea..fe3aa75f1f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,16 +6,6 @@ template: home.html Pixi is a **fast, modern, and reproducible** package management tool for developers of all backgrounds. -=== "Linux & macOS" - ```shell - curl -fsSL https://pixi.sh/install.sh | sh - ``` -=== "Windows" - ```powershell - powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex" - ``` -More installation options can be found [here](installation.md). - ## Highlights - [🔄 **Reproducibility**](workspace/lockfile.md) @@ -27,7 +17,7 @@ More installation options can be found [here](installation.md). - [🌐 **Multi Platform**](workspace/multi_platform_configuration.md) Works on Linux, macOS, Windows, and more. -- [🧩 **Multi Environment**](workspace/multi_environment.md) +- [🧩 **Multiple Environments**](workspace/multi_environment.md) Compose multiple environments in one manifest. - [🐍 **Python**](python/tutorial.md) @@ -128,7 +118,7 @@ To install `pixi`, run: pixi init hello-world cd hello-world ``` - 2. **Add dependencies:** + 2. **Add dependencies into the default environment:** ``` pixi add cowpy python ``` @@ -155,7 +145,7 @@ To install `pixi`, run: ||----w | || || ``` - 7. **Entry the environment shell:** + 7. **Enter the shell into the environment:** ``` pixi shell python hello.py diff --git a/docs/installation.md b/docs/installation.md index 488dbfe2d9..5088f66281 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -29,7 +29,7 @@ To install `pixi` you can run the following command in your terminal: The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `%UserProfile%\.pixi\bin`. The command will also add `%UserProfile%\.pixi\bin` to your `PATH` environment variable, allowing you to invoke `pixi` from anywhere. -Now restart your terminal or shell to make the installation effective. +Now restart your terminal or shell to make the installation take effect. ??? question "Don't trust our link? Check the script!" You can check the installation `sh` script: [download](https://pixi.sh/install.sh) and the `ps1`: [download](https://pixi.sh/install.ps1). @@ -121,16 +121,16 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try). The installation script has several options that can be manipulated through environment variables. - | Variable | Description | Default Value | - |----------------------|------------------------------------------------------------------------------------|-----------------------| - | `PIXI_VERSION` | The version of Pixi getting installed, can be used to up- or down-grade. | `latest` | - | `PIXI_HOME` | The location of the pixi home folder containing global environments and configs. | `$HOME/.pixi` | - | `PIXI_BIN_DIR` | The location where the standalone pixi binary should be installed. | `$PIXI_HOME/bin` | - | `PIXI_ARCH` | The architecture the Pixi version was built for. | `uname -m` | - | `PIXI_NO_PATH_UPDATE`| If set the `$PATH` will not be updated to add `pixi` to it. | | + | Variable | Description | Default Value | + |----------------------|---------------------------------------------------------------------------------------|-----------------------| + | `PIXI_VERSION` | The version of Pixi getting installed, can be used to up- or down-grade. | `latest` | + | `PIXI_HOME` | The location of the pixi home folder containing global environments and configs. | `$HOME/.pixi` | + | `PIXI_BIN_DIR` | The location where the standalone pixi binary should be installed. | `$PIXI_HOME/bin` | + | `PIXI_ARCH` | The architecture the Pixi version was built for. | `uname -m` | + | `PIXI_NO_PATH_UPDATE`| If set the `$PATH` will not be updated to add `pixi` to it. | | | `PIXI_DOWNLOAD_URL` | Overrides the download URL for the Pixi binary (useful for mirrors or custom builds). | GitHub releases, e.g. [linux-64](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-unknown-linux-musl.tar.gz) | - | `NETRC` | Path to a custom `.netrc` file for authentication with private repositories. | | - | `TMP_DIR` | The temporary directory the script uses to download to and unpack the binary from. | `/tmp` | + | `NETRC` | Path to a custom `.netrc` file for authentication with private repositories. | | + | `TMP_DIR` | The temporary directory the script uses to download to and unpack the binary from. | `/tmp` | For example, on Apple Silicon, you can force the installation of the x86 version: ```shell @@ -253,7 +253,7 @@ Afterwards, restart the shell or source the shell config file. ``` ## Uninstall -Before un-installation you might want to delete any previous files pixi has installed. +Before un-installation you might want to delete any files pixi managed. 1. Remove any cached data: ```shell diff --git a/docs/misc/FAQ.md b/docs/misc/FAQ.md index ff5e5fef6e..9ccc9043ce 100644 --- a/docs/misc/FAQ.md +++ b/docs/misc/FAQ.md @@ -27,6 +27,7 @@ We think the name sparks curiosity and fun, if you don't agree, I'm sorry, but y ``` ## Where is `pixi build` + **TL;DR**: It's coming we promise! `pixi build` is going to be the subcommand that can generate a conda package out of a Pixi workspace. diff --git a/docs/python/pyproject_toml.md b/docs/python/pyproject_toml.md index 72a8876487..697ec8cd42 100644 --- a/docs/python/pyproject_toml.md +++ b/docs/python/pyproject_toml.md @@ -108,9 +108,12 @@ As Pixi takes the conda dependencies over the pypi dependencies. ## Optional dependencies -If your python project includes groups of optional dependencies, Pixi will automatically interpret them as [Pixi features](../reference/pixi_manifest.md#the-feature-table) of the same name with the associated `pypi-dependencies`. +If your python project includes groups of optional dependencies, Pixi will automatically interpret +them as [Pixi features](../reference/pixi_manifest.md#the-feature-table) of the same name with the associated `pypi-dependencies`. -You can add them to Pixi environments manually, or use `pixi init` to setup the workspace, which will create one environment per feature. Self-references to other groups of optional dependencies are also handled. +You can add them to Pixi environments manually, or use `pixi init` to setup the workspace, +which will create one environment per feature. Self-references to other groups of optional +dependencies are also handled. For instance, imagine you have a project folder with a `pyproject.toml` file similar to: @@ -145,13 +148,15 @@ test = {features = ["test"], solve-group = "default"} all = {features = ["all"], solve-group = "default"} ``` -In this example, three environments will be created by pixi: +In this example, three environments will be created by Pixi: - **default** with 'package1' as pypi dependency - **test** with 'package1' and 'pytest' as pypi dependencies - **all** with 'package1', 'package2' and 'pytest' as pypi dependencies -All environments will be solved together, as indicated by the common `solve-group`, and added to the lock file. You can edit the `[tool.pixi.environments]` section manually to adapt it to your use case (e.g. if you do not need a particular environment). +All environments will be solved together, as indicated by the common `solve-group`, and +added to the lock file. You can edit the `[tool.pixi.environments]` section manually to adapt it to +your use case (e.g. if you do not need a particular environment). ## Dependency groups diff --git a/docs/python/pytorch.md b/docs/python/pytorch.md index 69a6673d46..2606d59f41 100644 --- a/docs/python/pytorch.md +++ b/docs/python/pytorch.md @@ -110,7 +110,7 @@ Best to do this per dependency to force the index to be used. --8<-- "docs/source_files/pyproject_tomls/pytorch-pypi.toml:minimal" ``` -You can tell Pixi to use multiple environment for the multiple versions of PyTorch, either `cpu` or `gpu`. +You can tell Pixi to use multiple environments for the multiple versions of PyTorch, either `cpu` or `gpu`. === "`pixi.toml`" ```toml title="Use multiple environments for the pypi pytorch installation" @@ -128,11 +128,12 @@ pixi run -e gpu python -c "import torch; print(torch.__version__); print(torch.c ``` ### Mixing MacOS and CUDA with `pypi-dependencies` + When using pypi-dependencies, Pixi creates a “solve” environment to resolve the PyPI dependencies. This process involves installing the Conda dependencies first and then resolving the PyPI packages within that environment. This can become problematic if you’re on a macOS machine and trying to resolve the CUDA version of PyTorch for Linux or Windows. -Since macOS doesn’t support those environments, the Conda dependencies for CUDA will fail to install, preventing proper resolution. +Since macOS doesn’t support the Conda dependencies for CUDA, it can't install the solve environment, preventing proper resolution. **Current Status:** The Pixi maintainers are aware of this limitation and are actively working on a solution to enable cross-platform dependency resolution for such cases. @@ -156,16 +157,21 @@ In the meantime, you may need to run the resolution process on a machine that su ``` ## Troubleshooting + When you had trouble figuring out why your PyTorch installation is not working, please share your solution or tips with the community by creating a **PR** to this documentation. #### Testing the `pytorch` installation + You can verify your PyTorch installation with this command: + ```shell pixi run python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" ``` #### Checking the CUDA version of your machine + To check which CUDA version Pixi detects on your machine, run: + ``` pixi info ``` @@ -185,17 +191,19 @@ nvidia-smi ``` To check the version of the CUDA toolkit installed in your environment: + ```shell pixi run nvcc --version ``` #### Reasons for broken installations + Broken installations often result from mixing incompatible channels or package sources: 1. **Mixing Conda Channels** Using both `conda-forge` and the legacy `pytorch` channel can cause conflicts. - Choose one channel and stick with it to avoid issues in the installed environment. + Choose one channel and stick with it to avoid issues in the environment. 2. **Mixing Conda and PyPI Packages** @@ -215,8 +223,10 @@ To summarize: 2. Using [PyPI](#installing-from-pypi) - Use the appropriate PyPI index to fetch the correct CUDA-enabled wheels. -#### Environment Resolution Failures +#### Resolution Failures + If you see an error like this: + **ABI tag mismatch** ``` ├─▶ failed to resolve pypi dependencies diff --git a/docs/python/tutorial.md b/docs/python/tutorial.md index 85d650afb5..73dc418617 100644 --- a/docs/python/tutorial.md +++ b/docs/python/tutorial.md @@ -77,7 +77,8 @@ Channels like `conda-forge` manage packages similar to PyPI but allow for differ The keyword `platforms` determines which platforms the workspace supports. The `pixi_py` package itself is added as an `editable` dependency. -This means that the package is installed in editable mode, so you can make changes to the package and see the changes reflected in the environment, without having to re-install the environment. +This means that the package is installed in editable mode, so you can make changes to the package and +see the changes reflected in the environment, without having to re-install it. ```toml # Editable installs @@ -153,8 +154,8 @@ dependencies = ["black", "flask[async]==3.1.0"] ### Installation: `pixi install` -Pixi always ensures the environment is up-to-date with the `pyproject.toml` file when running the environment. -If you want to do it manually, you can run: +Pixi always ensures the environment is up-to-date with the `pyproject.toml` file before running something in it. +If you want to do it manually anyway, you can run: ```shell pixi install @@ -164,7 +165,7 @@ We now have a new directory called `.pixi` in the workspace root. The environment is a Conda environment with all the Conda and PyPI dependencies installed into it. The environment is always a result of the `pixi.lock` file, which is generated from the `pyproject.toml` file. -This file contains the exact versions of the dependencies that were installed in the environment across platforms. +This file contains the exact versions of the dependencies that were installed into the environment across platforms. ## What's in the environment? @@ -208,9 +209,9 @@ Every environment in Pixi is isolated but reuses files that are hard-linked from This means that you can have multiple environments with the same packages but only have the individual files stored once on disk. ??? question "Why does the environment have a Python interpreter?" - The Python interpreter is also installed in the environment. + The Python interpreter is also installed into the environment. This is because the Python interpreter version is read from the `requires-python` field in the `pyproject.toml` file. - This is used to determine the Python version to install in the environment. + This is used to determine the Python version to install into the environment. This way, Pixi automatically manages/bootstraps the Python interpreter for you, so no more `brew`, `apt` or other system install steps. ??? question "How to use the Free-threaded interpreter?" @@ -218,7 +219,7 @@ This means that you can have multiple environments with the same packages but on ``` pixi add python-freethreading ``` - This ensures that a free-threaded version of Python is installed in the environment. + This ensures that a free-threaded version of Python is installed into the environment. This might not work with other packages that are not thread-safe yet. You can read more about free-threaded Python [here](https://docs.python.org/3/howto/free-threading-python.html). @@ -262,7 +263,7 @@ test = { features = ["test"], solve-group = "default" } By putting these in the same solve group, you ensure that the versions in `test` and `default` are exactly the same. Without specifying the environment name, Pixi will default to the `default` environment. -If you want to install or run the `test` environment, you can specify the environment with the `--environment` flag. +If you want to install or run the `test` environment, you add `--environment test` to the command. ```shell pixi install --environment test @@ -366,8 +367,8 @@ test_me.py . ??? question "Why didn't I have to specify the environment?" The `test` task was added to the `test` feature/environment. - When you run the `test` task, Pixi automatically switches to the `test` environment. - Because that is the only environment that has the task. + When you run the `test` task, Pixi automatically switches to the `test` environment, + because that is the only one associated with the `test` feature. Neat! It seems to be working! @@ -392,9 +393,10 @@ pytest 8.1.1 1.1 mib pypi pytest-8.1. ``` However, the default environment is missing the `pytest` package. -This way, you can finetune your environments to only have the packages that are needed for that environment. -E.g. you could also have a `dev` environment that has `pytest` and `ruff` installed, but you could omit these from the `prod` environment. -There is a [docker](https://github.com/prefix-dev/pixi/tree/main/examples/docker) example that shows how to set up a minimal `prod` environment and copy from there. +This way, you can finetune your environments to only have the packages that are needed. +E.g. you could also have a `dev` environment that has `pytest` and `ruff` installed, but +you could omit these from the `prod` environment. There is a [docker](https://github.com/prefix-dev/pixi/tree/main/examples/docker) +example that shows how to set up a minimal `prod` environment and copy from there. ## Replacing PyPI packages with conda packages diff --git a/docs/reference/pixi_manifest.md b/docs/reference/pixi_manifest.md index e7ca10ed0c..981235dc0d 100644 --- a/docs/reference/pixi_manifest.md +++ b/docs/reference/pixi_manifest.md @@ -1,6 +1,7 @@ The `pixi.toml` is the workspace manifest, also known as the Pixi workspace configuration file. -It specifies environments for a workspace, and the package dependency requirements for those environments. It can also specify tasks which can run in those environments, as well as many other configuration options. +It specifies environments for a workspace, and the package dependency requirements for +those environments. It can also specify tasks which can run in those environments, as well as many other configuration options. A `toml` file is structured in different tables. This document will explain the usage of the different tables. @@ -286,7 +287,7 @@ requires-pixi = ">=0.40,<1.0" !!! note This option should be used to improve the reproducibility of building the workspace. A complicated - requirement spec may be an obstacle to setup the building environment. + requirement spec may be an obstacle to setup the build environment. ### `exclude-newer` (optional) @@ -445,7 +446,9 @@ More information in the [system requirements documentation](../workspace/system_ ## The `pypi-options` table The `pypi-options` table is used to define options that are specific to PyPI registries. -These options can be specified either at the root level, which will add it to the default options feature, or on feature level, which will create a union of these options when the features are included in the environment. +These options can be specified either at the root level, which will add it to the default options feature, +or on feature level, which will create a union of these options when the features are included in the +environment. The options that can be defined are: @@ -471,9 +474,11 @@ Often you might want to use an alternative or extra index for your workspace. Th - `index-url`: replaces the main index url. If this is not set the default index used is `https://pypi.org/simple`. **Only one** `index-url` can be defined per environment. -- `extra-index-urls`: adds an extra index url. The urls are used in the order they are defined. And are preferred over the `index-url`. These are merged across features into an environment. +- `extra-index-urls`: adds an extra index url. The urls are used in the order they are defined. And + are preferred over the `index-url`. These are merged across features into an environment. - `find-links`: which can either be a path `{path = './links'}` or a url `{url = 'https://example.com/links'}`. - This is similar to the `--find-links` option in `pip`. These are merged across features into an environment. + This is similar to the `--find-links` option in `pip`. These are merged across features into an + environment. An example: @@ -491,6 +496,7 @@ There are some [examples](https://github.com/prefix-dev/pixi/tree/main/examples/ ### No Build Isolation + Even though build isolation is a good default. One can choose to **not** isolate the build for a certain package name, this allows the build to access the `pixi` environment. This is convenient if you want to use `torch` or something similar for your build-process. @@ -521,9 +527,13 @@ no-build-isolation = true ``` !!! tip "Conda dependencies define the build environment" - To use `no-build-isolation` effectively, use conda dependencies to define the build environment. These are installed before the PyPI dependencies are resolved, this way these dependencies are available during the build process. In the example above adding `torch` as a PyPI dependency would be ineffective, as it would not yet be installed during the PyPI resolution phase. + To use `no-build-isolation` effectively, use conda dependencies to define the build environment. + These are installed before the PyPI dependencies are resolved, this way these dependencies are + available during the build process. In the example above adding `torch` as a PyPI dependency + would be ineffective, as it would not yet be installed during the PyPI resolution phase. ### No Build + When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error. Can be either set per package or globally. @@ -540,7 +550,8 @@ no-build = ["package1", "package2"] When features are merged, the following priority is adhered: `no-build = true` > `no-build = ["package1", "package2"]` > `no-build = false` -So, to expand: if `no-build = true` is set for *any* feature in the environment, this will be used as the setting for the environment. +So, to expand: if `no-build = true` is set for *any* feature in the environment, this +will be used as the setting for the environment. ### No Binary @@ -563,7 +574,8 @@ no-binary = ["package1", "package2"] When features are merged, the following priority is adhered: `no-binary = true` > `no-binary = ["package1", "package2"]` > `no-binary = false` -So, to expand: if `no-binary = true` is set for *any* feature in the environment, this will be used as the setting for the environment. +So, to expand: if `no-binary = true` is set for *any* feature in the environment, this +will be used as the setting for the environment. ### Index Strategy @@ -928,7 +940,8 @@ clang = ">=16.0.6" ## The `feature` and `environments` tables The `feature` table allows you to define features that can be used to create different `[environments]`. -The `[environments]` table allows you to define different environments. The design is explained in the [this design document](../workspace/multi_environment.md). +The `[environments]` table allows you to define different environments. The design is +explained in the [this design document](../workspace/multi_environment.md). ```toml title="Simplest example" [feature.test.dependencies] @@ -1035,10 +1048,21 @@ test = {features = ["test"]} When an environment comprises several features (including the default feature): - The `activation` and `tasks` of the environment are the union of the `activation` and `tasks` of all its features. -- The `dependencies` and `pypi-dependencies` of the environment are the union of the `dependencies` and `pypi-dependencies` of all its features. This means that if several features define a requirement for the same package, both requirements will be combined. Beware of conflicting requirements across features added to the same environment. -- The `system-requirements` of the environment is the union of the `system-requirements` of all its features. If multiple features specify a requirement for the same system package, the highest version is chosen. -- The `channels` of the environment is the union of the `channels` of all its features. Channel priorities can be specified in each feature, to ensure channels are considered in the right order in the environment. -- The `platforms` of the environment is the intersection of the `platforms` of all its features. Be aware that the platforms supported by a feature (including the default feature) will be considered as the `platforms` defined at workspace level (unless overridden in the feature). This means that it is usually a good idea to set the workspace `platforms` to all platforms it can support across its environments. +- The `dependencies` and `pypi-dependencies` of the environment are the union of the + `dependencies` and `pypi-dependencies` of all its features. This means that if several features + define a requirement for the same package, both requirements will be combined. Beware of conflicting + requirements across features added to the same environment. +- The `system-requirements` of the environment is the union of the `system-requirements` + of all its features. If multiple features specify a requirement for the same system package, the + highest version is chosen. +- The `channels` of the environment is the union of the `channels` of all its features. + Channel priorities can be specified in each feature, to ensure channels are considered in the right + order in the environment. +- The `platforms` of the environment is the intersection of the `platforms` of all its features. + Be aware that the platforms supported by a feature (including the default feature) will be considered + as the `platforms` defined at workspace level (unless overridden in the feature). This means that + it is usually a good idea to set the workspace `platforms` to all platforms it can support across + its environments. ## Global configuration @@ -1177,6 +1201,7 @@ Each of these tables has a different purpose and is used to define the dependenc ### `build-dependencies` + Build dependencies are required in the build environment and contain all tools that are not needed on the host of the package. Following packages are examples of typical build dependencies: @@ -1214,6 +1239,7 @@ Following packages are typical examples for host dependencies: ``` ### `run-dependencies` + The `run-dependencies` are the packages that will be installed in the environment when the package is run. - Libraries diff --git a/docs/switching_from/conda.md b/docs/switching_from/conda.md index 293304b98a..39aa493e8b 100644 --- a/docs/switching_from/conda.md +++ b/docs/switching_from/conda.md @@ -27,7 +27,7 @@ This shift towards workspaces offers a more organized and efficient way to manag ??? tip "Activating Pixi environment in the current shell" For some advanced use-cases, you can activate the environment in the current shell. - This uses the `pixi shell-hook` which prints the activation script, which can be used to activate the environment in the current shell without `pixi` itself. + This uses the `pixi shell-hook` which prints the activation script, which can be used without `pixi` itself. ```shell ~/myenv > eval "$(pixi shell-hook)" ``` @@ -44,16 +44,19 @@ It manages more than one environment for more than one platform in a single work `conda` installs all environments in one global location. When this is important to you for filesystem reasons, you can use the [detached-environments](../reference/pixi_configuration.md#detached-environments) feature of pixi. + ```shell pixi config set detached-environments true # or a specific location pixi config set detached-environments /path/to/envs ``` + This will make the installation of the environments go to the same folder. `pixi` does have the `pixi global` command to install tools on your machine. (See [global](../reference/cli/pixi/global.md)) This is not a replacement for `conda` but works the same as [`pipx`](https://pipx.pypa.io/stable/) and [`condax`](https://mariusvniekerk.github.io/condax/). It creates a single isolated environment for the given requirement and installs the binaries into the global path. + ```shell pixi global install bat bat pixi.toml @@ -85,4 +88,5 @@ Encountering issues? Here are solutions to some common problems when being used - `pixi global install pip`, pip doesn't work. `pip` is installed in the global isolated environment. Use `pixi add pip` in a workspace to install `pip` in the workspace environment and use that workspace. - `pixi global install ` -> `import ` -> `ModuleNotFoundError: No module named ''` - The library is installed in the global isolated environment. Use `pixi add ` in a workspace to install the library in the workspace environment and use that workspace. + The library is installed in the global isolated environment. Use `pixi add ` in a workspace + to install the library in the workspace environment and use that workspace. diff --git a/docs/tutorials/import.md b/docs/tutorials/import.md index c7b047a888..1bd69d44eb 100644 --- a/docs/tutorials/import.md +++ b/docs/tutorials/import.md @@ -1,14 +1,22 @@ In this tutorial we will show you how to import existing environments into a Pixi workspace. In case some words used in the tutorial don't make sense to you, you may get value from first -reading some of our other tutorials, like [our first workspace walthrough](../first_workspace.md) and [our guide to multi-environment workspaces](./multi_environment.md). +reading some of our other tutorials, like [our first workspace walthrough](../first_workspace.md) and +[our guide to multi-environment workspaces](./multi_environment.md). ## `pixi import` -Within any Pixi workspace, you can use [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) to import an environment from a given file. At the time of writing, we support two import file formats: `conda-env` and `pypi-txt`. Running `pixi import` without providing a `format` will try each format in turn until one succeeds, or return an error if all formats fail. + +Within any Pixi workspace, you can use [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) +to import an environment from a given file. At the time of writing, we support two import +file formats: `conda-env` and `pypi-txt`. Running `pixi import` without providing a `format` will try +each format in turn until one succeeds, or return an error if all formats fail. If you don't already have a Pixi workspace, you can create one with [`pixi init`](https://pixi.sh/latest/reference/cli/pixi/init/). ### `conda-env` format -The `conda-env` format is for files in the conda ecosystem (typically called `environment.yml`) following [the syntax specified in the conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually). Suppose our environment to import is specified in this file: + +The `conda-env` format is for files in the conda ecosystem (typically called `environment.yml`) following +[the syntax specified in the conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually). +Suppose our environment to import is specified in this file: ```yaml title="environment.yml" name: simple-env @@ -19,7 +27,10 @@ dependencies: - httpx ``` -We can then run `pixi import --format=conda-env environment.yml` to import the environment into our workspace. By default, since our `environment.yml` has a `name` field, this creates a `feature` of the same name (or uses the feature of that name if it already exists), and creates an `environment` containing that feature (with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set): +We can then run `pixi import --format=conda-env environment.yml` to import the environment +into our workspace. By default, since our `environment.yml` has a `name` field, this creates a `feature` +of the same name (or uses the feature of that name if it already exists), and creates an `environment` +containing that feature (with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set): ```toml title="pixi.toml" [feature.simple-env] @@ -35,9 +46,14 @@ httpx = "*" simple-env = { features = ["simple-env"], no-default-feature = true } ``` -It is then possible to define tasks for that environment, run commands in that environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics! +It is then possible to define tasks for the imported environment, run commands in that +environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) +in that environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics! -For files without a `name` field, or to override the default behaviour, you can specify custom `--feature` and `--environment` names. This also allows importing into existing features and environments (including the `default` feature and environment). For example, given this other environment file to import: +For files without a `name` field, or to override the default behavior, you can specify custom +`--feature` and `--environment` names. This also allows importing into existing features and +environments (including the `default` feature and environment). For example, +given this other environment file to import: ```yaml title="env2.yml" channels: ["conda-forge"] @@ -45,7 +61,9 @@ dependencies: - numpy ``` -Running `pixi import --format=conda-env --feature=numpy --environment=simple-env env2.yml` will import the environment into a new feature called "numpy", and include that feature in the existing `simple-env` environment (effectively merging the environments from our two input files): +Running `pixi import --format=conda-env --feature=numpy --environment=simple-env env2.yml` will import +the environment into a new feature called "numpy", and include that feature in the existing +`simple-env` environment (effectively merging the environments from our two input files): ```toml title="pixi.toml" [feature.simple-env] @@ -67,7 +85,9 @@ numpy = "*" simple-env = { features = ["simple-env", "numpy"], no-default-feature = true } ``` -It is also possible to specify platforms for the feature via the `--platform` argument. For example, `pixi import --format=conda-env --feature=unix --platform=linux-64 --platform=osx-arm64 environment.yml` adds the following to our workspace manifest: +It is also possible to specify platforms for the feature via the `--platform` argument. For example, +`pixi import --format=conda-env --feature=unix --platform=linux-64 --platform=osx-arm64 environment.yml` +adds the following to our workspace manifest: ```toml title="pixi.toml" [feature.unix] @@ -85,6 +105,7 @@ unix = { features = ["unix"], no-default-feature = true } ``` ### `pypi-txt` format + The `pypi-txt` format is for files in the PyPI ecosystem following [the requirements file format specification in the `pip` docs](https://pip.pypa.io/en/stable/reference/requirements-file-format/). Suppose our environment to import is specified in this file: @@ -94,7 +115,10 @@ cowpy array-api-extra>=0.8 ``` -We can then run `pixi import --format=pypi-txt --feature=my-feature1 requirements.txt` to import the environment into our workspace. It is necessary to specify a `feature` or `environment` name (or both) via the arguments of the same names. If only one of these names is provided, a matching name is used for the other field. Hence, the following lines are added to our workspace manifest: +We can then run `pixi import --format=pypi-txt --feature=my-feature1 requirements.txt` to import the +environment into our workspace. It is necessary to specify a `feature` or `environment` +name (or both) via the arguments of the same names. If only one of these names is provided, a matching +name is used for the other field. Hence, the following lines are added to our workspace manifest: ```toml title="pixi.toml" [feature.my-feature1.pypi-dependencies] @@ -105,14 +129,23 @@ array-api-extra = ">=0.8" my-feature1 = { features = ["my-feature1"], no-default-feature = true } ``` -Any dependencies listed in the file are added as [`pypi-dependencies`](https://pixi.sh/latest/reference/pixi_manifest/#pypi-dependencies). An environment will be created with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set if the given environment name does not already exist. +Any dependencies listed in the file are added as [`pypi-dependencies`](https://pixi.sh/latest/reference/pixi_manifest/#pypi-dependencies). +An environment will be created with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) +set if the given environment name does not already exist. -It is then possible to define tasks for that environment, run commands in that environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics! +It is then possible to define tasks for that environment, run commands in that +environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that +environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics! -Just like the `conda-env` format, it is possible to import into existing features/environments (including the `default` feature/environment), and set specific platforms for the feature. See the previous section for details. +Just like the `conda-env` format, it is possible to import into existing features/environments +(including the `default` feature/environment), and set specific platforms for the feature. See the previous section for details. ## `pixi init --import` -It is also possible to combine the steps of `pixi init` and `pixi import` into one, via [`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). For example, `pixi init --import environment.yml` (using the same file from our example above) produces a manifest which looks like this: + +It is also possible to combine the steps of `pixi init` and `pixi import` into one, via +[`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). For example, +`pixi init --import environment.yml` (using the same file from our example above) produces a manifest +which looks like this: ```toml title="pixi.toml" [workspace] @@ -131,7 +164,8 @@ python = "*" httpx = "*" ``` -Unlike `pixi import`, this by default uses the `default` feature and environment. Thus, it achieves a very similar workspace to that obtained by running `pixi init ` and `pixi import --feature=default environment.yml`. +Unlike `pixi import`, this by default uses the `default` feature and environment. Thus, +it achieves a very similar workspace to that obtained by running `pixi init ` and `pixi import --feature=default environment.yml`. One difference is that `pixi init --import` will by default inherit its name from the given import file (if the file specifies the `name` field), rather than from its working directory. @@ -139,6 +173,7 @@ One difference is that `pixi init --import` will by default inherit its name fro At the time of writing, only the `conda-env` format is supported by `pixi init --import`. ## Conclusion + For further details, please see the CLI reference documentation for [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) and [`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). If there are any questions, or you know how to improve this tutorial, feel free to reach out to us on [GitHub](https://github.com/prefix-dev/pixi). diff --git a/docs/tutorials/ros2.md b/docs/tutorials/ros2.md index 0a0af6852d..3202cdf318 100644 --- a/docs/tutorials/ros2.md +++ b/docs/tutorials/ros2.md @@ -66,7 +66,7 @@ Now run the `turtlesim` example. pixi run ros2 run turtlesim turtlesim_node ``` -**Or** use the `shell` command to start an activated environment in your terminal. +**Or** use the `shell` command to start a shell in the activated environment in your terminal. ```shell pixi shell @@ -222,8 +222,8 @@ Let's inspire the community together! ### What happens with `rosdep`? -Currently, we don't support `rosdep` in a Pixi environment, so you'll have to add the packages using `pixi add`. -`rosdep` will call `conda install` which isn't supported in a Pixi environment. +Currently, we don't support `rosdep` in a Pixi environment, so you'll +have to add the packages using `pixi add`. `rosdep` will call `conda install` which isn't supported in a Pixi environment. ### Where can I find more documentation on the `robostack-*` channels? diff --git a/docs/tutorials/rust.md b/docs/tutorials/rust.md index a259297aa2..d625391e96 100644 --- a/docs/tutorials/rust.md +++ b/docs/tutorials/rust.md @@ -60,9 +60,9 @@ Now that you have rust installed, you can create a `cargo` project in your `pixi pixi run cargo init ``` -`pixi run` is pixi's way to run commands in the `pixi` environment, it will make sure that the environment is set up correctly for the command to run. +`pixi run` is pixi's way to run commands in an environment. It will make sure that the environment is activated for the command to run. It runs its own cross-platform shell, if you want more information checkout the [`tasks` documentation](../workspace/advanced_tasks.md). -You can also activate the environment in your own shell by running `pixi shell`, after that you don't need `pixi run ...` anymore. +You can also activate the environment in a shell by running `pixi shell`, after that you don't need `pixi run ...` anymore. Now we can build a `cargo` project using `pixi`. ```shell diff --git a/docs/workspace/advanced_tasks.md b/docs/workspace/advanced_tasks.md index 4442f54e60..f16550b5cc 100644 --- a/docs/workspace/advanced_tasks.md +++ b/docs/workspace/advanced_tasks.md @@ -120,9 +120,12 @@ When you run the main task, Pixi ensures each dependent task uses its specified pixi run test-all ``` -The environment specified for a task dependency takes precedence over the environment specified via the CLI `--environment` flag. This means even if you run `pixi run test-all --environment py312`, the first dependency will still run in the `py311` environment as specified in the TOML file. +The environment specified for a task dependency takes precedence over the environment specified via +the CLI `--environment` flag. This means even if you run `pixi run test-all --environment py312`, +the first dependency will still run in the `py311` environment as specified in the TOML file. -In the example above, the `test-all` task runs the `test` task in both Python 3.11 and 3.12 environments, allowing you to verify compatibility across different Python versions with a single command. +In the example above, the `test-all` task runs the `test` task in both Python 3.11 and 3.12 environments, +allowing you to verify compatibility across different Python versions with a single command. ## Working directory @@ -390,7 +393,7 @@ Notes on environment variables in tasks: If you previously relied on a certain priority which no longer applies, you may need to change your task definitions. - For the specific case of overriding `task.env` with outside environment variables, this behaviour can + For the specific case of overriding `task.env` with outside environment variables, this behavior can now be recreated using [task arguments](#task-arguments). For example, if you were previously using a setup like: @@ -405,7 +408,7 @@ Notes on environment variables in tasks: world ``` - you can now recreate this behaviour like: + you can now recreate this behavior like: ```toml title="pixi.toml" [tasks] @@ -419,6 +422,7 @@ Notes on environment variables in tasks: ``` ## Clean environment + You can make sure the environment of a task is "Pixi only". Here Pixi will only include the minimal required environment variables for your platform to run the command in. The environment will contain all variables set by the conda environment like `"CONDA_PREFIX"`. diff --git a/docs/workspace/environment.md b/docs/workspace/environment.md index efa2000bad..2675c587d0 100644 --- a/docs/workspace/environment.md +++ b/docs/workspace/environment.md @@ -12,7 +12,7 @@ To do the activation we have multiple options: - `pixi shell`: start a shell with the environment activated. - `pixi shell-hook`: print the command to activate the environment in your current shell. -- `pixi run` run a command or [task](./advanced_tasks.md) in the environment. +- `pixi run` run a command or [task](./advanced_tasks.md) in the default environment. Where the `run` command is special as it runs its own cross-platform shell and has the ability to run tasks. More information about tasks can be found in the [tasks documentation](./advanced_tasks.md). @@ -59,7 +59,7 @@ Find the reference for the `activation` table [here](../reference/pixi_manifest. ## Structure -A Pixi environment is located in the `.pixi/envs` directory of the workspace by default. +All Pixi environments are by default located in the `.pixi/envs` directory of the workspace. This keeps your machine and your workspace clean and isolated from each other, and makes it easy to clean up after a workspace is done. While this structure is generally recommended, environments can also be stored outside of workspace directories by enabling [detached environments](../reference/pixi_configuration.md#detached-environments). @@ -86,10 +86,10 @@ If you look at the `.pixi/envs` directory, you will see a directory for each env These directories are conda environments, and you can use them as such, but you cannot manually edit them, this should always go through the `pixi.toml`. Pixi will always make sure the environment is in sync with the `pixi.lock` file. -If this is not the case then all the commands that use the environment will automatically update the environment, e.g. `pixi run`, `pixi shell`. +If this is not the case then all the commands that use the environment will automatically it, e.g. `pixi run`, `pixi shell`. -### Environment Installation Metadata -On environment installation, Pixi will write a small file to the environment that contains some metadata about installation. +### Environment Metadata +On environment creation, Pixi will add a small file containing some metadata. This file is called `pixi` and is located in the `conda-meta` folder of the environment. This file contains the following information: @@ -112,7 +112,7 @@ If the hash of the `pixi.lock` file is different from the hash in the `pixi` fil This is used to speedup activation, in order to trigger a full revalidation and installation use `pixi install` or `pixi reinstall`. A broken environment would typically not be found with a hash comparison, but a revalidation would reinstall the environment. -By default, all lock file modifying commands will always use the revalidation and on `pixi install` it always revalidates. +By default, all lock file modifying commands will always trigger a revalidation, as does `pixi install`. ### Cleaning up @@ -132,10 +132,12 @@ rm -rf .pixi/envs/cuda ## Solving environments -When you run a command that uses the environment, Pixi will check if the environment is in sync with the `pixi.lock` file. +When you run a command that uses the environment, Pixi will check if it is in sync with the `pixi.lock` file. If it is not, Pixi will solve the environment and update it. -This means that Pixi will retrieve the best set of packages for the dependency requirements that you specified in the `pixi.toml` and will put the output of the solve step into the `pixi.lock` file. -Solving is a mathematical problem and can take some time, but we take pride in the way we solve environments, and we are confident that we can solve your environment in a reasonable time. +This means that Pixi will retrieve the best set of packages for the dependency requirements that you +specified in the `pixi.toml` and will put the output of the solve step into the `pixi.lock` file. +Solving is a mathematical problem and can take some time, but we take pride in the way we solve +environments, and we are confident that we can solve yours in a reasonable time. If you want to learn more about the solving process, you can read these: - [Rattler(conda) resolver blog](https://prefix.dev/blog/the_new_rattler_resolver) diff --git a/docs/workspace/lockfile.md b/docs/workspace/lockfile.md index 2807bb2e8f..1a1643cdea 100644 --- a/docs/workspace/lockfile.md +++ b/docs/workspace/lockfile.md @@ -59,10 +59,10 @@ The lock file contains two definitions: Pixi uses the lock file for the following reasons: - To save a working installation state, without copying the entire environment's data. -- To ensure the workspace configuration is aligned with the installed environment. +- To ensure the workspace configuration is aligned with the environment. - To give the user a file that contains all the information about the environment. -This gives you (and your collaborators) a way to really reproduce the environment they are working in. +This gives you (and your collaborators) a way to really reproduce environment they are working in. Using tools such as docker suddenly becomes much less necessary. ## When is a lock file generated? @@ -172,4 +172,4 @@ rm pixi.lock This will remove the lock file, and the next time you run a command that requires the lock file, it will be generated again. !!! Warning "Note" - This does remove the locked state of the environment, and the environment will be updated to the latest version of the packages. + This does remove the locked state of the environment, which will be updated to the latest version of all packages.