diff --git a/crates/pixi_build_type_conversions/src/project_model.rs b/crates/pixi_build_type_conversions/src/project_model.rs index 948e089b11..e916cfcbb3 100644 --- a/crates/pixi_build_type_conversions/src/project_model.rs +++ b/crates/pixi_build_type_conversions/src/project_model.rs @@ -229,7 +229,7 @@ mod tests { #[rstest] #[test] fn test_conversions_v1_docs( - #[files("../../docs/source_files/pixi_projects/pixi_build_*/pixi.toml")] + #[files("../../docs/source_files/pixi_workspaces/pixi_build/*/pixi.toml")] manifest_path: PathBuf, ) { snapshot_test!(manifest_path); diff --git a/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_cpp.snap b/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@cpp.snap similarity index 100% rename from crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_cpp.snap rename to crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@cpp.snap diff --git a/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_python.snap b/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@python.snap similarity index 100% rename from crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_python.snap rename to crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@python.snap diff --git a/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_workspace.snap b/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@workspace.snap similarity index 100% rename from crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_workspace.snap rename to crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@workspace.snap diff --git a/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_workspace_variants.snap b/crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@workspace_variants.snap similarity index 100% rename from crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@pixi_build_workspace_variants.snap rename to crates/pixi_build_type_conversions/src/snapshots/pixi_build_type_conversions__project_model__tests__conversions_v1_docs@workspace_variants.snap diff --git a/docs/Community.md b/docs/Community.md index f6f96179f4..5b76ef3cf5 100644 --- a/docs/Community.md +++ b/docs/Community.md @@ -1,8 +1,3 @@ ---- -part: pixi -title: Community -description: Who is using pixi? ---- # Community When you want to show your users and contributors that they can use pixi in your repo, you can use the following badge: diff --git a/docs/FAQ.md b/docs/FAQ.md index 9449c221d5..1a5ddd3944 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,8 +1,3 @@ ---- -part: pixi -title: Frequently asked questions -description: What questions did we encounter more often? ---- ## What is the difference with `conda`, `mamba`, `poetry`, `pip` | Tool | Installs python | Builds packages | Runs predefined tasks | Has lock files builtin | Fast | Use without python | diff --git a/docs/advanced/channel_priority.md b/docs/advanced/channel_logic.md similarity index 96% rename from docs/advanced/channel_priority.md rename to docs/advanced/channel_logic.md index c40a0acf30..e876edf695 100644 --- a/docs/advanced/channel_priority.md +++ b/docs/advanced/channel_logic.md @@ -1,13 +1,16 @@ +# Channel Logic + All logic regarding the decision which dependencies can be installed from which channel is done by the instruction we give the solver. The actual code regarding this is in the [`rattler_solve`](https://github.com/conda/rattler/blob/02e68c9539c6009cc1370fbf46dc69ca5361d12d/crates/rattler_solve/src/resolvo/mod.rs) crate. This might however be hard to read. Therefore, this document will continue with simplified flow charts. -# Channel specific dependencies +## Channel specific dependencies + When a user defines a channel per dependency, the solver needs to know the other channels are unusable for this dependency. ```toml -[project] +[workspace] channels = ["conda-forge", "my-channel"] [dependencies] @@ -32,7 +35,7 @@ flowchart TD Channel priority is dictated by the order in the `project.channels` array, where the first channel is the highest priority. For instance: ```toml -[project] +[workspace] channels = ["conda-forge", "my-channel", "your-channel"] ``` If the package is found in `conda-forge` the solver will not look for it in `my-channel` and `your-channel`, because it tells the solver they are excluded. @@ -62,7 +65,7 @@ If you have 10 channels and the package is found in the 5th channel it will excl # Use case: pytorch and nvidia with conda-forge A common use case is to use `pytorch` with `nvidia` drivers, while also needing the `conda-forge` channel for the main dependencies. ```toml -[project] +[workspace] channels = ["nvidia/label/cuda-11.8.0", "nvidia", "conda-forge", "pytorch"] platforms = ["linux-64"] @@ -92,10 +95,10 @@ If you want to force a specific priority for a channel, you can use the `priorit The higher the number, the higher the priority. Non specified priorities are set to 0 but the index in the array still counts as a priority, where the first in the list has the highest priority. -This priority definition is mostly important for [multiple environments](../features/multi_environment.md) with different channel priorities, as by default feature channels are prepended to the project channels. +This priority definition is mostly important for [multiple environments](../environments/multi_environment.md) with different channel priorities, as by default feature channels are prepended to the project channels. ```toml -[project] +[workspace] name = "test_channel_priority" platforms = ["linux-64", "osx-64", "win-64", "osx-arm64"] channels = ["conda-forge"] diff --git a/docs/advanced/explain_info_command.md b/docs/advanced/explain_info_command.md index dc716896c5..7a88396fba 100644 --- a/docs/advanced/explain_info_command.md +++ b/docs/advanced/explain_info_command.md @@ -1,8 +1,3 @@ ---- -part: pixi/advanced -title: Info command -description: Learn what the info command reports ---- `pixi info` prints out useful information to debug a situation or to get an overview of your machine/project. This information can also be retrieved in `json` format using the `--json` flag, which can be useful for programmatically reading it. @@ -57,11 +52,11 @@ In that case, if pixi cannot find the `__cuda` virtual package on your machine t ### Cache dir The directory where pixi stores its cache. -Checkout the [cache documentation](../features/environment.md#caching-packages) for more information. +Checkout the [cache documentation](../environments/environment.md#caching-packages) for more information. ### Auth storage -Check the [authentication documentation](authentication.md) +Check the [authentication documentation](../deployment/authentication.md) ### Cache size diff --git a/docs/advanced/installation.md b/docs/advanced/installation.md new file mode 100644 index 0000000000..a753e59085 --- /dev/null +++ b/docs/advanced/installation.md @@ -0,0 +1,190 @@ +# Installation + +To install `pixi` you can run the following command in your terminal: + +=== "Linux & macOS" + ```bash + curl -fsSL https://pixi.sh/install.sh | bash + ``` + + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. + The script will also extend the `PATH` environment variable in the startup script of your shell to include `~/.pixi/bin`. + This allows you to invoke `pixi` from anywhere. + +=== "Windows" + ```powershell + powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex" + ``` + + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. + The command will also add `LocalAppData/pixi/bin` to your `PATH` environment variable, allowing you to invoke `pixi` from anywhere. + +!!! tip + + You might need to restart your terminal or source your shell for the changes to take effect. + +## Update + +Updating is as simple as installing, rerunning the installation script gets you the latest version. + +```shell +pixi self-update +``` +Or get a specific pixi version using: +```shell +pixi self-update --version x.y.z +``` + +!!! note + If you've used a package manager like `brew`, `mamba`, `conda`, `paru` etc. to install `pixi` + you must use the built-in update mechanism. e.g. `brew upgrade pixi`. + + +## Alternative Installation Methods + +Although we recommend installing pixi through the above method we also provide additional installation methods. + +### Homebrew + +Pixi is available via homebrew. To install pixi via homebrew simply run: + +```shell +brew install pixi +``` + +### Windows Installer + +We provide an `msi` installer on [our GitHub releases page](https://github.com/prefix-dev/pixi/releases/latest). +The installer will download pixi and add it to the path. + +### Winget + +``` +winget install prefix-dev.pixi +``` + +### Install From Source + +pixi is 100% written in Rust, and therefore it can be installed, built and tested with cargo. +To start using pixi from a source build run: + +```shell +cargo install --locked --git https://github.com/prefix-dev/pixi.git pixi +``` + +We don't publish to `crates.io` anymore, so you need to install it from the repository. +The reason for this is that we depend on some unpublished crates which disallows us to publish to `crates.io`. + +or when you want to make changes use: + +```shell +cargo build +cargo test +``` + +If you have any issues building because of the dependency on `rattler` checkout +its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try). + + +## Installer Script Options + +=== "Linux & macOS" + + 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 binary folder. | `$HOME/.pixi` | + | `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. | | + | `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 + curl -fsSL https://pixi.sh/install.sh | PIXI_ARCH=x86_64 bash + ``` + Or set the version + ```shell + curl -fsSL https://pixi.sh/install.sh | PIXI_VERSION=v0.18.0 bash + ``` + +=== "Windows" + + The installation script has several options that can be manipulated through environment variables. + + | Variable | Environment variable | Description | Default Value | + |------------------|----------------------|-----------------------------------------------------------------------------------|-----------------------------| + | `PixiVersion` | `PIXI_VERSION` |The version of pixi getting installed, can be used to up- or down-grade. | `latest` | + | `PixiHome` | `PIXI_HOME` | The location of the installation. | `$Env:USERPROFILE\.pixi` | + | `NoPathUpdate` | | If set, the `$PATH` will not be updated to add `pixi` to it. | | + + For example, set the version using: + + ```powershell + iwr -useb https://pixi.sh/install.ps1 | iex -Args "-PixiVersion v0.18.0" + ``` + + +## Autocompletion + +To get autocompletion follow the instructions for your shell. +Afterwards, restart the shell or source the shell config file. + + +### Bash (default on most Linux systems) + +Add the following to the end of `~/.bashrc`: + +```bash title="~/.bashrc" + +eval "$(pixi completion --shell bash)" +``` +### Zsh (default on macOS) + +Add the following to the end of `~/.zshrc`: + + +```zsh title="~/.zshrc" + +autoload -Uz compinit && compinit # redundant with Oh My Zsh +eval "$(pixi completion --shell zsh)" +``` + +### PowerShell (pre-installed on all Windows systems) + +Add the following to the end of `Microsoft.PowerShell_profile.ps1`. +You can check the location of this file by querying the `$PROFILE` variable in PowerShell. +Typically the path is `~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1` or +`~/.config/powershell/Microsoft.PowerShell_profile.ps1` on -Nix. + +```pwsh +(& pixi completion --shell powershell) | Out-String | Invoke-Expression +``` + +### Fish + +Add the following to the end of `~/.config/fish/config.fish`: + +```fish title="~/.config/fish/config.fish" + +pixi completion --shell fish | source +``` + +### Nushell + +Add the following to your Nushell config file (find it by running `$nu.config-path` in Nushell): + +```nushell +mkdir $"($nu.data-dir)/vendor/autoload" +pixi completion --shell nushell | save --force $"($nu.data-dir)/vendor/autoload/pixi-completions.nu" +``` + +### Elvish + +Add the following to the end of `~/.elvish/rc.elv`: + +```elv title="~/.elvish/rc.elv" + +eval (pixi completion --shell elvish | slurp) +``` diff --git a/docs/advanced/shebang.md b/docs/advanced/shebang.md index 05ab34518c..4361585f6e 100644 --- a/docs/advanced/shebang.md +++ b/docs/advanced/shebang.md @@ -1,8 +1,3 @@ ---- -part: pixi/advanced -title: Self-contained scripts -description: Learn how to write self-contained shell scripts using `pixi exec` ---- # Using `pixi exec` to create self-contained scripts diff --git a/docs/basic_usage.md b/docs/basic_usage.md deleted file mode 100644 index 6d659ebc75..0000000000 --- a/docs/basic_usage.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -part: pixi -title: Basic usage -description: Taking your first steps with pixi ---- -Ensure you've got `pixi` set up. If running `pixi` doesn't show the help, see the [getting started](index.md) if it doesn't. - -```shell -pixi -``` - -Initialize a new project and navigate to the project directory. - -```shell -pixi init pixi-hello-world -cd pixi-hello-world -``` - -Add the dependencies you would like to use. - -```shell -pixi add python -``` - -Create a file named `hello_world.py` in the directory and paste the following code into the file. - -```py title="hello_world.py" -def hello(): - print("Hello World, to the new revolution in package management.") - -if __name__ == "__main__": - hello() -``` - -Run the code inside the environment. - -```shell -pixi run python hello_world.py -``` - -You can also put this run command in a **task**. - -```shell -pixi task add hello python hello_world.py -``` - -After adding the task, you can run the task using its name. - -```shell -pixi run hello -``` - -Use the `shell` command to activate the environment and start a new shell in there. - -```shell -pixi shell -python -exit() -``` - -You've just learned the basic features of pixi: - -1. initializing a project -2. adding a dependency. -2. adding a task, and executing it. -3. running a program. - -Feel free to play around with what you just learned like adding more tasks, dependencies or code. - -Happy coding! - -## Use pixi as a global installation tool - -Use pixi to install tools on your machine. - -Some notable examples: - -```shell -# Awesome cross shell prompt, huge tip when using pixi! -pixi global install starship - -# Want to try a different shell? -pixi global install fish - -# Install other prefix.dev tools -pixi global install rattler-build - -# Install a multi package environment -pixi global install --environment data-science-env --expose python --expose jupyter python jupyter numpy pandas -``` - -## Use pixi in GitHub Actions - -You can use pixi in GitHub Actions to install dependencies and run commands. -It supports automatic caching of your environments. - -```yml -- uses: prefix-dev/setup-pixi@v0.5.1 -- run: pixi run cowpy "Thanks for using pixi" -``` - -See the [GitHub Actions](./advanced/github_actions.md) for more details. diff --git a/docs/build/cpp.md b/docs/build/cpp.md index 9f67e4ebc2..4441610aff 100644 --- a/docs/build/cpp.md +++ b/docs/build/cpp.md @@ -42,7 +42,7 @@ Next up we'll create the: Use the following `pixi.toml` file, you can hover over the annotations to see why each step was added. ```toml ---8<-- "docs/source_files/pixi_projects/pixi_build_cpp/pixi.toml" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/cpp/pixi.toml" ``` 1. Add the **preview** feature `pixi-build` that enables pixi to build the package. @@ -60,7 +60,7 @@ Use the following `pixi.toml` file, you can hover over the annotations to see wh Next lets add the `CMakeList.txt` file: ```CMake ---8<-- "docs/source_files/pixi_projects/pixi_build_cpp/CMakeLists.txt" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/cpp/CMakeLists.txt" ``` 1. Find `python`, this actually finds anything above 3.8, but we are using 3.8 as a minimum version. @@ -75,7 +75,7 @@ Next lets add the `CMakeList.txt` file: Next lets add the `src/bindings.cpp` file, this one is quite simple: ```cpp ---8<-- "docs/source_files/pixi_projects/pixi_build_cpp/src/bindings.cpp" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/cpp/src/bindings.cpp" ``` 1. We define a function that will be used to add two numbers together. diff --git a/docs/build/python.md b/docs/build/python.md index 6349ac9dc2..090f473849 100644 --- a/docs/build/python.md +++ b/docs/build/python.md @@ -37,14 +37,14 @@ The Python package has a single function `main`. Calling that, will print a table containing the name, age and city of three people. ```py title="src/rich_example/__init__.py" ---8<-- "docs/source_files/pixi_projects/pixi_build_python/src/rich_example/__init__.py" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/python/src/rich_example/__init__.py" ``` The metadata of the Python package is defined in `pyproject.toml`. ```toml title="pyproject.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_python/pyproject.toml" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/python/pyproject.toml" ``` 1. We use the `rich` package to print the table in the terminal. @@ -86,12 +86,12 @@ We pass `--format pixi` in order to communicate to pixi, that we want a `pixi.to This is the content of the `pixi.toml`: ```toml title="pixi.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_python/pixi.toml" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/python/pixi.toml" ``` 1. In `workspace` information is set that is shared across all packages in the workspace. 2. In `dependencies` you specify all of your pixi packages. Here, this includes only our own package that is defined further below under `package` -3. We define a task that runs the `rich-example-main` executable we defined earlier. You can learn more about tasks in this [section](../features/advanced_tasks.md) +3. We define a task that runs the `rich-example-main` executable we defined earlier. You can learn more about tasks in this [section](../environments/advanced_tasks.md) 4. In `package` we define the actual pixi package. This information will be used when other pixi packages or workspaces depend on our package or when we upload it to a conda channel. 5. The same way, Python uses build backends to build a Python package, pixi uses build backends to build pixi packages. `pixi-build-python` creates a pixi package out of a Python package. 6. In `package.host-dependencies`, we add Python dependencies that are necessary to build the Python package. By adding them here as well, the dependencies will come from the conda channel rather than PyPI. diff --git a/docs/build/variants.md b/docs/build/variants.md index b460bf8049..89fc06e84a 100644 --- a/docs/build/variants.md +++ b/docs/build/variants.md @@ -22,7 +22,7 @@ As a reminder, we ended up with a top-level `pixi.toml` containing the workspace Our workspace then depended on `rich_example` and `python_bindings`. ```toml title="pixi.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace_variants/pixi.toml:dependencies" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace_variants/pixi.toml:dependencies" ``` The file tree looks like this: @@ -46,7 +46,7 @@ The file tree looks like this: In order to allow multiple Python versions we first have to change the Python version requirement of `python_bindings` from `3.12.*` to `*`. ```toml title="packages/python_bindings/pixi.toml" hl_lines="4" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace_variants/packages/python_bindings/pixi.toml:host-dependencies" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace_variants/packages/python_bindings/pixi.toml:host-dependencies" ``` 1. Used to be "3.12.*" @@ -55,7 +55,7 @@ Now, we have to specify the Python versions we want to allow. We do that in `workspace.build-variants`: ```toml title="pixi.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace_variants/pixi.toml:variants" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace_variants/pixi.toml:variants" ``` If we'd run `pixi install` now, we'd leave it up to pixi whether to use Python 3.11 or 3.12. @@ -64,7 +64,7 @@ In our case this allows us to test our setup against both Python 3.11 and 3.12. ```toml title="pixi.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace_variants/pixi.toml:environments" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace_variants/pixi.toml:environments" ``` By running `pixi list` we can see the Python version used in each environment. diff --git a/docs/build/workspace.md b/docs/build/workspace.md index a688a65e04..c18d48ec90 100644 --- a/docs/build/workspace.md +++ b/docs/build/workspace.md @@ -42,7 +42,7 @@ Within a pixi manifest, you can manage a workspace and/or describe a package. In the case of `rich_example` we choose to do both, so the only thing we have to add is the dependency on the `python_bindings`. ```py title="pixi.toml" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace/pixi.toml:workspace" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace/pixi.toml:workspace" ``` We only want to use the `workspace` table of the top-level manifest. @@ -83,7 +83,7 @@ Luckily `python_bindings` exposes a function `add` which allows us to do exactly ```py title="src/rich_example/__init__.py" ---8<-- "docs/source_files/pixi_projects/pixi_build_workspace/src/rich_example/__init__.py" +--8<-- "docs/source_files/pixi_workspaces/pixi_build/workspace/src/rich_example/__init__.py" ``` If you run `pixi run start`, the age of each person should now be accurate: diff --git a/docs/advanced/authentication.md b/docs/deployment/authentication.md similarity index 98% rename from docs/advanced/authentication.md rename to docs/deployment/authentication.md index d279460151..816fa040a9 100644 --- a/docs/advanced/authentication.md +++ b/docs/deployment/authentication.md @@ -1,8 +1,3 @@ ---- -part: pixi -title: Authenticate pixi with a server -description: Authenticate pixi to access private channels ---- You can authenticate pixi with a server like prefix.dev, a private quetz instance or anaconda.org. Different servers use different authentication methods. @@ -67,7 +62,7 @@ pixi auth login s3://my-bucket --s3-access-key-id --s3-secret-ac ``` !!!note - S3 authentication is also supported through AWS's typical `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, see the [S3 section](../advanced/s3.md) for more details. + S3 authentication is also supported through AWS's typical `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, see the [S3 section](s3.md) for more details. ## Where does pixi store the authentication information? diff --git a/docs/deployment/container.md b/docs/deployment/container.md new file mode 100644 index 0000000000..87aafcbcd9 --- /dev/null +++ b/docs/deployment/container.md @@ -0,0 +1,59 @@ +# Bringing pixi to production + +You can bring pixi projects into production by either containerizing it using tools like Docker or Podman. + + + +We provide a simple docker image at [`pixi-docker`](https://github.com/prefix-dev/pixi-docker) that contains the pixi executable on top of different base images. + +The images are available on [ghcr.io/prefix-dev/pixi](https://ghcr.io/prefix-dev/pixi). + +There are different tags for different base images available: + +- `latest` - based on `ubuntu:jammy` +- `focal` - based on `ubuntu:focal` +- `bullseye` - based on `debian:bullseye` +- `jammy-cuda-12.2.2` - based on `nvidia/cuda:12.2.2-jammy` +- ... and more + +!!!tip "All tags" + For all tags, take a look at the [build script](https://github.com/prefix-dev/pixi-docker/blob/main/.github/workflows/build.yml). + +### Example usage + +The following example uses the pixi docker image as a base image for a multi-stage build. +It also makes use of `pixi shell-hook` to not rely on pixi being installed in the production container. + +!!!tip "More examples" + For more examples, take a look at [pavelzw/pixi-docker-example](https://github.com/pavelzw/pixi-docker-example). + +```Dockerfile +FROM ghcr.io/prefix-dev/pixi:0.41.4 AS build + +# copy source code, pixi.toml and pixi.lock to the container +WORKDIR /app +COPY . . +# install dependencies to `/app/.pixi/envs/prod` +# use `--locked` to ensure the lockfile is up to date with pixi.toml +RUN pixi install --locked -e prod +# create the shell-hook bash script to activate the environment +RUN pixi shell-hook -e prod -s bash > /shell-hook +RUN echo "#!/bin/bash" > /app/entrypoint.sh +RUN cat /shell-hook >> /app/entrypoint.sh +# extend the shell-hook script to run the command passed to the container +RUN echo 'exec "$@"' >> /app/entrypoint.sh + +FROM ubuntu:24.04 AS production +WORKDIR /app +# only copy the production environment into prod container +# please note that the "prefix" (path) needs to stay the same as in the build container +COPY --from=build /app/.pixi/envs/prod /app/.pixi/envs/prod +COPY --from=build --chmod=0755 /app/entrypoint.sh /app/entrypoint.sh +# copy your project code into the container as well +COPY ./my_project /app/my_project + +EXPOSE 8000 +ENTRYPOINT [ "/app/entrypoint.sh" ] +# run your app inside the pixi environment +CMD [ "uvicorn", "my_project:app", "--host", "0.0.0.0" ] +``` diff --git a/docs/advanced/production_deployment.md b/docs/deployment/pixi_pack.md similarity index 64% rename from docs/advanced/production_deployment.md rename to docs/deployment/pixi_pack.md index e5c2641bd8..aaacf2388b 100644 --- a/docs/advanced/production_deployment.md +++ b/docs/deployment/pixi_pack.md @@ -1,70 +1,4 @@ -# Bringing pixi to production - -You can bring pixi projects into production by either containerizing it using tools like Docker or by using [`quantco/pixi-pack`](https://github.com/quantco/pixi-pack). - -!!!tip "" - [@pavelzw](https://github.com/pavelzw) from [QuantCo](https://quantco.com) wrote a blog post about bringing pixi to production. You can read it [here](https://tech.quantco.com/blog/pixi-production). - -## Docker - - - -We provide a simple docker image at [`pixi-docker`](https://github.com/prefix-dev/pixi-docker) that contains the pixi executable on top of different base images. - -The images are available on [ghcr.io/prefix-dev/pixi](https://ghcr.io/prefix-dev/pixi). - -There are different tags for different base images available: - -- `latest` - based on `ubuntu:jammy` -- `focal` - based on `ubuntu:focal` -- `bullseye` - based on `debian:bullseye` -- `jammy-cuda-12.2.2` - based on `nvidia/cuda:12.2.2-jammy` -- ... and more - -!!!tip "All tags" - For all tags, take a look at the [build script](https://github.com/prefix-dev/pixi-docker/blob/main/.github/workflows/build.yml). - -### Example usage - -The following example uses the pixi docker image as a base image for a multi-stage build. -It also makes use of `pixi shell-hook` to not rely on pixi being installed in the production container. - -!!!tip "More examples" - For more examples, take a look at [pavelzw/pixi-docker-example](https://github.com/pavelzw/pixi-docker-example). - -```Dockerfile -FROM ghcr.io/prefix-dev/pixi:0.42.1 AS build - -# copy source code, pixi.toml and pixi.lock to the container -WORKDIR /app -COPY . . -# install dependencies to `/app/.pixi/envs/prod` -# use `--locked` to ensure the lockfile is up to date with pixi.toml -RUN pixi install --locked -e prod -# create the shell-hook bash script to activate the environment -RUN pixi shell-hook -e prod -s bash > /shell-hook -RUN echo "#!/bin/bash" > /app/entrypoint.sh -RUN cat /shell-hook >> /app/entrypoint.sh -# extend the shell-hook script to run the command passed to the container -RUN echo 'exec "$@"' >> /app/entrypoint.sh - -FROM ubuntu:24.04 AS production -WORKDIR /app -# only copy the production environment into prod container -# please note that the "prefix" (path) needs to stay the same as in the build container -COPY --from=build /app/.pixi/envs/prod /app/.pixi/envs/prod -COPY --from=build --chmod=0755 /app/entrypoint.sh /app/entrypoint.sh -# copy your project code into the container as well -COPY ./my_project /app/my_project - -EXPOSE 8000 -ENTRYPOINT [ "/app/entrypoint.sh" ] -# run your app inside the pixi environment -CMD [ "uvicorn", "my_project:app", "--host", "0.0.0.0" ] -``` - -## pixi-pack - +# Pixi Pack [`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. diff --git a/docs/advanced/s3.md b/docs/deployment/s3.md similarity index 99% rename from docs/advanced/s3.md rename to docs/deployment/s3.md index 8b0f8766ca..b5a1637359 100644 --- a/docs/advanced/s3.md +++ b/docs/deployment/s3.md @@ -3,7 +3,7 @@ If you want to use S3 object storage to fetch your packages, you can use the `s3://` protocol as a channel. ```toml title="pixi.toml" -[project] +[workspace] # ... channels = ["s3://my-bucket/custom-channel"] ``` @@ -147,7 +147,7 @@ Public buckets that don't need authentication can be used by just specifying the For example, on AWS, you might have a bucket that is publicly accessible via `https://my-public-bucket.s3.eu-central-1.amazonaws.com`. ```toml title="pixi.toml" -[project] +[workspace] channels = ["https://my-public-bucket.s3.eu-central-1.amazonaws.com/channel"] ``` diff --git a/docs/features/advanced_tasks.md b/docs/environments/advanced_tasks.md similarity index 99% rename from docs/features/advanced_tasks.md rename to docs/environments/advanced_tasks.md index cac89ce5a6..078b95b8a4 100644 --- a/docs/features/advanced_tasks.md +++ b/docs/environments/advanced_tasks.md @@ -1,8 +1,3 @@ ---- -part: pixi/advanced -title: Advanced tasks -description: Learn how to interact with pixi tasks ---- When building a package, you often have to do more than just run the code. Steps like formatting, linting, compiling, testing, benchmarking, etc. are often part of a project. diff --git a/docs/features/environment.md b/docs/environments/environment.md similarity index 99% rename from docs/features/environment.md rename to docs/environments/environment.md index 0e7482c862..ff07cc5ba5 100644 --- a/docs/features/environment.md +++ b/docs/environments/environment.md @@ -1,8 +1,3 @@ ---- -part: pixi -title: Environment -description: The resulting environment of a pixi installation. ---- # Environments diff --git a/docs/features/lockfile.md b/docs/environments/lockfile.md similarity index 100% rename from docs/features/lockfile.md rename to docs/environments/lockfile.md diff --git a/docs/features/multi_environment.md b/docs/environments/multi_environment.md similarity index 98% rename from docs/features/multi_environment.md rename to docs/environments/multi_environment.md index d17572d486..4ce98f177f 100644 --- a/docs/features/multi_environment.md +++ b/docs/environments/multi_environment.md @@ -186,7 +186,7 @@ It's possible to define tasks in multiple environments, in this case the user sh Here is a simple example of a task only manifest: ```toml title="pixi.toml" -[project] +[workspace] name = "test_ambiguous_env" channels = [] platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"] @@ -249,10 +249,9 @@ Dev ``` -## Important links +## Initial write-up -- Initial writeup of the proposal: [GitHub Gist by 0xbe7a](https://gist.github.com/0xbe7a/bbf8a323409be466fe1ad77aa6dd5428) -- GitHub project: [#10](https://github.com/orgs/prefix-dev/projects/10) +Initial write-up of the proposal: [GitHub Gist by 0xbe7a](https://gist.github.com/0xbe7a/bbf8a323409be466fe1ad77aa6dd5428) ## Real world example use cases @@ -263,7 +262,7 @@ Dev This can be replaced by using multiple environments. ```toml title="pixi.toml" - [project] + [workspace] name = "polarify" # ... channels = ["conda-forge"] @@ -353,7 +352,7 @@ Dev This is a common use case where we want to test the production environment with additional dependencies. ```toml title="pixi.toml" - [project] + [workspace] name = "my-app" # ... channels = ["conda-forge"] @@ -409,7 +408,7 @@ Dev This is an example for an ML project that should be executable on a machine that supports `cuda` and `mlx`. It should also be executable on machines that don't support `cuda` or `mlx`, we use the `cpu` feature for this. ```toml title="pixi.toml" - [project] + [workspace] name = "my-ml-project" description = "A project that does ML stuff" authors = ["Your Name "] diff --git a/docs/features/multi_platform_configuration.md b/docs/environments/multi_platform_configuration.md similarity index 96% rename from docs/features/multi_platform_configuration.md rename to docs/environments/multi_platform_configuration.md index 81e0037f0d..035a236f20 100644 --- a/docs/features/multi_platform_configuration.md +++ b/docs/environments/multi_platform_configuration.md @@ -1,8 +1,3 @@ ---- -part: pixi/advanced -title: Multi platform config -description: Learn how to set up for different platforms/OS's ---- [Pixi's vision](../vision.md) includes being supported on all major platforms. Sometimes that needs some extra configuration to work well. On this page, you will learn what you can configure to align better with the platform you are making your application for. @@ -11,7 +6,7 @@ Here is an example manifest file that highlights some of the features: === "`pixi.toml`" ```toml title="pixi.toml" - [project] + [workspace] # Default project info.... # A list of platforms you are supporting with your package. platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] @@ -33,7 +28,7 @@ Here is an example manifest file that highlights some of the features: ``` === "`pyproject.toml`" ```toml title="pyproject.toml" - [tool.pixi.project] + [tool.pixi.workspace] # Default project info.... # A list of platforms you are supporting with your package. platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] diff --git a/docs/features/system_requirements.md b/docs/environments/system_requirements.md similarity index 100% rename from docs/features/system_requirements.md rename to docs/environments/system_requirements.md diff --git a/docs/examples/cpp-sdl.md b/docs/examples/cpp-sdl.md deleted file mode 100644 index 1f3f971144..0000000000 --- a/docs/examples/cpp-sdl.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -part: pixi/examples -title: SDL example -description: How to build and run an SDL application in C++ ---- - -![](https://storage.googleapis.com/prefix-cms-images/docs/sdl_examle.png) - -The `cpp-sdl` example is located in the pixi repository. - -```shell -git clone https://github.com/prefix-dev/pixi.git -``` - -Move to the example folder - -```shell -cd pixi/examples/cpp-sdl -``` - -Run the `start` command - -```shell -pixi run start -``` - -Using the [`depends-on`](../features/advanced_tasks.md#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks. - -```shell -# Configure the CMake project -pixi run configure - -# Build the executable -pixi run build - -# Start the build executable -pixi run start -``` diff --git a/docs/examples/opencv.md b/docs/examples/opencv.md deleted file mode 100644 index 1703e5ba11..0000000000 --- a/docs/examples/opencv.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -part: pixi/examples -title: Opencv example -description: How to run opencv using pixi ---- - -The `opencv` example is located in the pixi repository. - -```shell -git clone https://github.com/prefix-dev/pixi.git -``` - -Move to the example folder - -```shell -cd pixi/examples/opencv -``` - -## Face detection - -Run the `start` command to start the face detection algorithm. - -```shell -pixi run start -``` - -The screen that starts should look like this: - -![](https://storage.googleapis.com/prefix-cms-images/docs/opencv_face_recognition.png) - -Check out the `webcame_capture.py` to see how we detect a face. - -## Camera Calibration - -Next to face recognition, a camera calibration example is also included. - -You'll need a checkerboard for this to work. -Print this: - -[![chessboard](https://github.com/opencv/opencv/blob/4.x/doc/pattern.png?raw=true)](https://github.com/opencv/opencv/blob/4.x/doc/pattern.png) - -Then run - -```shell -pixi run calibrate -``` - -To make a picture for calibration press `SPACE` -Do this approximately 10 times with the chessboard in view of the camera - -After that press `ESC` which will start the calibration. - -When the calibration is done, the camera will be used again to find the distance to the checkerboard. - -![](https://storage.googleapis.com/prefix-cms-images/docs/calibration_board_detected.png) diff --git a/docs/examples/ros2-nav2.md b/docs/examples/ros2-nav2.md deleted file mode 100644 index 728eafc733..0000000000 --- a/docs/examples/ros2-nav2.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -part: pixi/examples -title: Navigation 2 example -description: How to run Nav2 using pixi ---- - - - -The `nav2` example is located in the pixi repository. - -```shell -git clone https://github.com/prefix-dev/pixi.git -``` - -Move to the example folder - -```shell -cd pixi/examples/ros2-nav2 -``` - -Run the `start` command - -```shell -pixi run start -``` diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000000..24489ae2b0 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,111 @@ +# Getting Started + + +Every Pixi workspace is described by a Pixi manifest. +In this simple example we have a single task `start` which runs a Python file and two dependencies, `cowpy` and `python`. + +```toml title="pixi.toml" +--8<-- "docs/source_files/pixi_workspaces/introduction/task_add/pixi.toml" +``` + +`channels` describes where our dependencies come from and `platforms` which platforms we support. +However, you might wonder why we need to specify the platforms if Pixi could just extract this information from your operating system. +That is because every dependency in your environment is stored in the lockfile called `pixi.lock`. +This ensures that even if you run your workspace on a different platform, the environment will contain exactly the dependencies that were solved on your machine. +This is one of the core features that makes pixi reproducible. +Learn more about lock files in [this chapter](./environments/lockfile.md). + + +## Multiple environments + +We already have a quite powerful setup which is sufficient for many use cases. +However, certain things are hard to do with the way things are set up right now. +What if I wanted to check if my script works with multiple versions of Python? +There cannot be multiple versions of the same package in one environment. +Luckily, Pixi is able to manage multiple environments! + +Environments are composed of features, so let's create a `py312` and `py313` features each with `python` set to a different version. +Then we will add those features to environments of the same name. + +```toml title="pixi.toml" hl_lines="12-20" +--8<-- "docs/source_files/pixi_workspaces/introduction/multi_env/pixi.toml" +``` + +Pixi does two things behind the scenes which might not be immediately obvious. +First, it automatically creates both a feature and environment called `default`. +`[dependencies]` and `[tasks]` belong to that feature. +Second, it adds the `default` feature to each environment unless you explicitly opt-out. +That means you can read the manifest as if it were declared like this: + +```toml hl_lines="6 9 19 20 21" +[workspace] +channels = ["conda-forge"] +name = "hello-world" +platforms = ["linux-64", "osx-arm64", "win-64"] + +[feature.default.tasks] +start = 'python hello.py' + +[feature.default.dependencies] +cowpy = "1.1.*" + +[feature.py312.dependencies] +python = "3.12.*" + +[feature.py313.dependencies] +python = "3.13.*" + +[environments] +default = ["default"] +py312 = ["default", "py312"] +py313 = ["default", "py313"] +``` + +Let's adapt the Python script so that it displays the current Python version: + +```py title="hello.py" +--8<-- "docs/source_files/pixi_workspaces/introduction/multi_env/hello.py" +``` + +The task `start` is available in both `py312` and `py313`, so we can test the script like this to test against Python 3.12: + +```bash +pixi run --environment=py312 start +``` + +``` + _________________________ +< Hello from Python 3.12! > + ------------------------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` + +And we can run this command to try it with Python 3.13: + + +```bash +pixi run --environment=py312 start +``` + +``` + _________________________ +< Hello from Python 3.12! > + ------------------------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` + + +## Going further + +There is still much more that pixi has to offer. +Check out the topics on the sidebar on the left to learn more. + +And don't forget to [join our Discord](https://discord.gg/kKV8ZxyzY4) to join our community of Pixi enthusiasts! diff --git a/docs/features/global_tools.md b/docs/global_tools/introduction.md similarity index 99% rename from docs/features/global_tools.md rename to docs/global_tools/introduction.md index 0d94fa8014..900051f732 100644 --- a/docs/features/global_tools.md +++ b/docs/global_tools/introduction.md @@ -136,7 +136,7 @@ dependencies = { snakemake = "*" } exposed = { snakemake = "snakemake" } ``` -More information on channels can be found [here](../advanced/channel_priority.md). +More information on channels can be found [here](../advanced/channel_logic.md). ### Automatic Exposed diff --git a/docs/index.md b/docs/index.md index 0a754869fd..dd0a8c5083 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,19 @@ ---- -part: pixi -title: Getting Started -description: Package management made easy ---- -# Getting Started +# Pixi + ![Pixi with magic wand](assets/pixi.webp) Pixi is a package management tool for developers. + +- ๐Ÿงช **Conda**: Leverage the existing conda ecosystem to obtain packages written in Python, C, C++, and many other languages. +- ๐Ÿ”„ **Reproducibility**: Work in dedicated, isolated environments that can be easily recreated. +- ๐Ÿ› ๏ธ **Tasks**: Manage complex pipelines effortlessly. +- ๐ŸŒ **Multi Platform**: Ensure compatibility across Linux, macOS, Windows, and more. +- ๐Ÿงฉ **Multi Environment**: Compose multiple environments within a single pixi manifest. +- ๐Ÿ—๏ธ **Building**: Build packages from source using powerful build backends. +- ๐Ÿ“ฆ **Distributing**: Distribute your software via conda channels or various other options. +- ๐Ÿ **Python**: Full support for `pyproject.toml` and PyPI dependencies. +- ๐ŸŒ **Global Tools**: Install globally available tools, safely stored in separate environments. + It allows the developer to install libraries and applications in a reproducible way. Use pixi cross-platform, on Windows, Mac and Linux. @@ -20,205 +27,108 @@ 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 `~/.pixi/bin`. - If this directory does not already exist, the script will create it. - - The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. + The script will also extend the `PATH` environment variable in the startup script of your shell to include `~/.pixi/bin`. + This allows you to invoke `pixi` from anywhere. === "Windows" - `PowerShell`: ```powershell powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex" ``` - Changing the [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) allows running a script from the internet. - Check the script you would be running with: - ```powershell - powershell -c "irm -useb https://pixi.sh/install.ps1 | more" - ``` - `winget`: - ``` - winget install prefix-dev.pixi - ``` - The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. - If this directory does not already exist, the script will create it. - - The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere. + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. + The command will also add `LocalAppData/pixi/bin` to your `PATH` environment variable, allowing you to invoke `pixi` from anywhere. !!! tip You might need to restart your terminal or source your shell for the changes to take effect. -You can find more options for the installation script [here](#installer-script-options). - -## Autocompletion - -To get autocompletion follow the instructions for your shell. -Afterwards, restart the shell or source the shell config file. - +Check out our [installation docs](./advanced/installation.md) to learn about alternative installation methods, autocompletion and more. -### Bash (default on most Linux systems) +## Getting Started -Add the following to the end of `~/.bashrc`: -```bash title="~/.bashrc" +Initialize a new project and navigate to the project directory. -eval "$(pixi completion --shell bash)" +```bash +pixi init hello-world +cd hello-world ``` -### Zsh (default on macOS) -Add the following to the end of `~/.zshrc`: +This will create a pixi manifest which is a file called `pixi.toml`. +It describes the structure, dependencies and metadata of your workspace. - -```zsh title="~/.zshrc" - -autoload -Uz compinit && compinit # redundant with Oh My Zsh -eval "$(pixi completion --shell zsh)" +```toml title="pixi.toml" +--8<-- "docs/source_files/pixi_workspaces/introduction/init/pixi.toml" ``` -### PowerShell (pre-installed on all Windows systems) +Let's add dependencies! -Add the following to the end of `Microsoft.PowerShell_profile.ps1`. -You can check the location of this file by querying the `$PROFILE` variable in PowerShell. -Typically the path is `~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1` or -`~/.config/powershell/Microsoft.PowerShell_profile.ps1` on -Nix. - -```pwsh -(& pixi completion --shell powershell) | Out-String | Invoke-Expression +```bash +pixi add cowpy python ``` -### Fish - -Add the following to the end of `~/.config/fish/config.fish`: +The dependencies are not only installed, but also tracked in the manifest. -```fish title="~/.config/fish/config.fish" - -pixi completion --shell fish | source +```toml title="pixi.toml" hl_lines="6-8" +--8<-- "docs/source_files/pixi_workspaces/introduction/deps_add/pixi.toml" ``` -### Nushell - -Add the following to your Nushell config file (find it by running `$nu.config-path` in Nushell): +We can now create a Python script which uses the `cowpy` library. -```nushell -mkdir $"($nu.data-dir)/vendor/autoload" -pixi completion --shell nushell | save --force $"($nu.data-dir)/vendor/autoload/pixi-completions.nu" +```py title="hello.py" +--8<-- "docs/source_files/pixi_workspaces/introduction/deps_add/hello.py" ``` -### Elvish - -Add the following to the end of `~/.elvish/rc.elv`: +The dependencies are installed in a pixi environment. +In order to run a command within an environment, we prefix it with `pixi run`. -```elv title="~/.elvish/rc.elv" - -eval (pixi completion --shell elvish | slurp) +```bash +pixi run python hello.py ``` - -## Alternative installation methods - -Although we recommend installing pixi through the above method we also provide additional installation methods. - -### Homebrew - -Pixi is available via homebrew. To install pixi via homebrew simply run: - -```shell -brew install pixi ``` + __________________ +< Hello Pixi fans! > + ------------------ + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || -### Windows installer - -We provide an `msi` installer on [our GitHub releases page](https://github.com/prefix-dev/pixi/releases/latest). -The installer will download pixi and add it to the path. - -### Install from source - -pixi is 100% written in Rust, and therefore it can be installed, built and tested with cargo. -To start using pixi from a source build run: - -```shell -cargo install --locked --git https://github.com/prefix-dev/pixi.git pixi ``` -We don't publish to `crates.io` anymore, so you need to install it from the repository. -The reason for this is that we depend on some unpublished crates which disallows us to publish to `crates.io`. -or when you want to make changes use: +You can also put this run command in a **task**. -```shell -cargo build -cargo test +```bash +pixi task add hello python hello.py ``` -If you have any issues building because of the dependency on `rattler` checkout -its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try). - -### Installer script options - -=== "Linux & macOS" - - 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 binary folder. | `$HOME/.pixi` | - | `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. | | - | `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 - curl -fsSL https://pixi.sh/install.sh | PIXI_ARCH=x86_64 bash - ``` - Or set the version - ```shell - curl -fsSL https://pixi.sh/install.sh | PIXI_VERSION=v0.18.0 bash - ``` - -=== "Windows" - - The installation script has several options that can be manipulated through environment variables. - - | Variable | Environment variable | Description | Default Value | - |------------------|----------------------|-----------------------------------------------------------------------------------|-----------------------------| - | `PixiVersion` | `PIXI_VERSION` |The version of pixi getting installed, can be used to up- or down-grade. | `latest` | - | `PixiHome` | `PIXI_HOME` | The location of the installation. | `$Env:USERPROFILE\.pixi` | - | `NoPathUpdate` | | If set, the `$PATH` will not be updated to add `pixi` to it. | | - - For example, set the version using: - - ```powershell - iwr -useb https://pixi.sh/install.ps1 | iex -Args "-PixiVersion v0.18.0" - ``` -## Update +```toml title="pixi.toml" hl_lines="6-7" +--8<-- "docs/source_files/pixi_workspaces/introduction/task_add/pixi.toml" +``` -Updating is as simple as installing, rerunning the installation script gets you the latest version. +After adding the task, you can run the task using its name. -```shell -pixi self-update -``` -Or get a specific pixi version using: -```shell -pixi self-update --version x.y.z +```bash +pixi run start ``` -!!! note - If you've used a package manager like `brew`, `mamba`, `conda`, `paru` etc. to install `pixi` - you must use the built-in update mechanism. e.g. `brew upgrade pixi`. +``` + __________________ +< Hello Pixi fans! > + ------------------ + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || -## Uninstall +``` -To uninstall pixi from your system, simply remove the binary. -=== "Linux & macOS" - ```shell - rm ~/.pixi/bin/pixi - ``` -=== "Windows" - ```shell - $PIXI_BIN = "$Env:LocalAppData\pixi\bin\pixi"; Remove-Item -Path $PIXI_BIN - ``` +You now know how to add dependencies and tasks to your environment. +Put the workspace folder on a different machine, and you will find that Pixi will be able to fully reproduce your setup. -After this command, you can still use the tools you installed with pixi. -To remove these as well, just remove the whole `~/.pixi` directory and remove the directory from your path. +If you want to learn more about Pixi, check out the next page! diff --git a/docs/advanced/github_actions.md b/docs/integration/ci/github_actions.md similarity index 97% rename from docs/advanced/github_actions.md rename to docs/integration/ci/github_actions.md index f7fb24b634..9ce0723367 100644 --- a/docs/advanced/github_actions.md +++ b/docs/integration/ci/github_actions.md @@ -1,8 +1,3 @@ ---- -part: pixi/advanced -title: GitHub Action -description: Learn how to use pixi using GitHub Actions ----