docs(src/assets/): update pixi official documentation

Author: KemingHe

src/assets/pixi/_metadata.json

@@ -1,6 +1,6 @@
 {
   "source_repo": "prefix-dev/pixi",
   "docs_path": "docs",
-  "updated_at": "2025-11-18T22:05:48Z",
-  "commit_sha": "4aa99b2f59bb07b24c51a24909a99064f6c6ad75"
+  "updated_at": "2025-11-25T22:05:53Z",
+  "commit_sha": "6638d0a3b70ab87c3968adc4b31ab796b9a3c0c1"
 }

src/assets/pixi/advanced/channel_logic.md

@@ -46,7 +46,7 @@ flowchart TD
     B --> C{Loop Over Channels}
     C --> D{Package in This Channel?}
     D -->|No| C
-    D -->|Yes| E{"This the first channel
+    D -->|Yes| E{"Is this the first channel
      for this package?"}
     E -->|Yes| F[Include Package in Candidates]
     E -->|No| G[Exclude Package from Candidates]

src/assets/pixi/concepts/conda_pypi.md

@@ -30,7 +30,7 @@ Here is a non-exhaustive comparison of the features of conda and PyPI ecosystems
 | Package index | [`conda-forge`](https://prefix.dev/channels/conda-forge), [`bioconda`](https://prefix.dev/channels/bioconda), and more | [pypi.org](https://pypi.org) |
 
 ## `uv` by Astral
-Pixi uses the [`uv`](https:://github.com/astral-sh/uv) library to handle PyPI packages.
+Pixi uses the [`uv`](https://github.com/astral-sh/uv) library to handle PyPI packages.
 Pixi doesn't install `uv` (the tool) itself: because both tools are built in Rust, it is used as a library.
 
 We're extremely grateful to the [Astral](https://astral.sh) team for their work on `uv`, which is a great library that allows us to handle PyPI packages in a much better way than before.
@@ -44,7 +44,7 @@ Initially, next to `pixi` we were building a library called `rip` which had the
 Because Pixi supports both ecosystems, it currently needs two different solvers to handle the dependencies.
 
 - The [`resolvo`](https://github.com/prefix-dev/resolvo) library is used to solve the conda dependencies. Implemented in [`rattler`](https://github.com/conda/rattler).
-- The [`PubGrub`](https://github.com/pubgrub-rs/pubgrub) library is used to solve the PyPI dependencies. Implemented in [`uv`](https:://github.com/astral-sh/uv).
+- The [`PubGrub`](https://github.com/pubgrub-rs/pubgrub) library is used to solve the PyPI dependencies. Implemented in [`uv`](https://github.com/astral-sh/uv).
 
 !!! Note
     The holy grail of Pixi is to have a single solver that can handle both ecosystems.

src/assets/pixi/first_workspace.md

@@ -39,7 +39,7 @@ version = "0.1.0"
 ```
 
 ??? tip "Do you want autocompletion of the manifest file?"
-    As `pixi.toml` has a JSON schema, it is possible to use IDE’s like VSCode to edit the field with autocompletion.
+    As `pixi.toml` has a JSON schema, it is possible to use IDEs like VSCode to edit the field with autocompletion.
     Install the [Even Better TOML VSCode extension](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) to get the best experience.
     Or use the integrated schema support in PyCharm.
 

src/assets/pixi/getting_started.md

@@ -1,6 +1,6 @@
 # Basic usage of Pixi
 
-Pixi can do alot of things, but it is designed to be simple to use.
+Pixi can do a lot of things, but it is designed to be simple to use.
 Let's go through the basic usage of Pixi.
 
 ## Managing workspaces
@@ -68,7 +68,7 @@ This can be a predefined task or any normal executable.
 - [`pixi task add`](./reference/cli/pixi/task/add.md) - Add a new task to the manifest
 
 Tasks can have other tasks as dependencies.
-Here is an example of a more complex task usecase
+Here is an example of a more complex task use case
 ```toml title="pixi.toml"
 [tasks]
 build = "make build"

src/assets/pixi/installation.md

@@ -22,7 +22,7 @@ To install `pixi` you can run the following command in your terminal:
     Or run:
 
     ```powershell
-    powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"
+    powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"
     ```
 
     ??? note "What does this do?"
@@ -111,7 +111,7 @@ cargo build
 cargo test
 ```
 
-If you have any issues building because of the dependency on `rattler` checkout
+If you have any issues building because of the dependency on `rattler` check out
 its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
 
 
@@ -124,9 +124,12 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     | 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_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`                |
 
     For example, on Apple Silicon, you can force the installation of the x86 version:
@@ -138,6 +141,40 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     curl -fsSL https://pixi.sh/install.sh | PIXI_VERSION=v0.18.0 bash
     ```
 
+    To make a "drop-in" installation of pixi directly in the user `$PATH`:
+    ```shell
+    curl -fsSL https://pixi.sh/install.sh | PIXI_BIN_DIR=/usr/local/bin PIXI_NO_PATH_UPDATE=1 bash
+    ```
+
+    #### Using `.netrc` for Authentication
+
+    If you need to download Pixi from a private repository that requires authentication, you can use a `.netrc` file instead of hardcoding credentials in the `PIXI_DOWNLOAD_URL`.
+
+    The install script automatically uses `.netrc` for authentication with `curl` and `wget`. By default, it looks for `~/.netrc`. You can specify a custom location using the `NETRC` environment variable:
+
+    ```shell
+    # Use the default ~/.netrc file
+    curl -fsSL https://pixi.sh/install.sh | PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash
+    ```
+
+    ```shell
+    # Use a custom .netrc file
+    curl -fsSL https://pixi.sh/install.sh | NETRC=/path/to/custom/.netrc PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash
+    ```
+
+    Your `.netrc` file should contain credentials in the following format:
+    ```
+    machine private.example.com
+    login your-username
+    password your-token-or-password
+    ```
+
+    !!! tip "Security Recommendation"
+        Using `.netrc` is more secure than embedding credentials directly in the `PIXI_DOWNLOAD_URL` (e.g., `https://user:[email protected]/file`), as it keeps credentials separate from the URL and prevents them from appearing in logs or process listings.
+
+    !!! tip "Security Note"
+        The install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output.
+
 === "Windows"
 
     The installation script has several options that can be manipulated through environment variables.
@@ -147,12 +184,24 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     | `PIXI_VERSION`       | The version of Pixi getting installed, can be used to up- or down-grade.          | `latest`                    |
     | `PIXI_HOME`          | The location of the installation.                                                 | `$Env:USERPROFILE\.pixi`    |
     | `PIXI_NO_PATH_UPDATE`| If set, the `$PATH` will not be updated to add `pixi` to it.                      | `false`                     |
+    | `PIXI_DOWNLOAD_URL`  | Overrides the download URL for the Pixi binary (useful for mirrors or custom builds). | GitHub releases, e.g. [win-64](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-pc-windows-msvc.zip)           |
 
     For example, set the version:
     ```powershell
     $env:PIXI_VERSION='v0.18.0'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex"
     ```
 
+    #### Authentication for Private Repositories
+
+    If you need to download Pixi from a private repository that requires authentication, you can embed credentials in the `PIXI_DOWNLOAD_URL`. The install script will automatically mask credentials in its output for security.
+
+    ```powershell
+    $env:PIXI_DOWNLOAD_URL='https://username:[email protected]/pixi-latest.zip'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex"
+    ```
+
+    !!! tip "Security Note"
+        The PowerShell install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output.
+
 ## Autocompletion
 
 To get autocompletion follow the instructions for your shell.
@@ -214,7 +263,7 @@ Before un-installation you might want to delete any previous files pixi has inst
     ```shell
     cd path/to/workspace && pixi clean
     ```
-3. Remove the `pixi` and it's global environments
+3. Remove the `pixi` and its global environments
     ```shell
     rm -r ~/.pixi
     ```

src/assets/pixi/misc/FAQ.md

@@ -1,6 +1,6 @@
 ## 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                                                     |
+| Tool   | Installs Python | Builds packages | Runs predefined tasks | Has lock files builtin | Fast | Use without python                                                     |
 |--------|-----------------|-----------------|-----------------------|-----------------------|------|------------------------------------------------------------------------|
 | Conda  | ✅               | ❌               | ❌                     | ❌                     | ❌    | ❌                                                                      |
 | Mamba  | ✅               | ❌               | ❌                     | ❌                     | ✅    | [✅](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) |

src/assets/pixi/reference/pixi_configuration.md

@@ -93,13 +93,23 @@ workspace manifest.
 
 ### `tls-no-verify`
 
-When set to true, the TLS certificates are not verified.
+When set to true, TLS certificate verification is disabled for all network connections, including both conda channels and PyPI registries.
+You can override this from the CLI with `--tls-no-verify`.
 
 !!! warning
 
     This is a security risk and should only be used for testing purposes or internal networks.
 
-You can override this from the CLI with `--tls-no-verify`.
+This is a global setting that affects all connections. 
+If you only need to bypass TLS verification for specific PyPI hosts, consider using [`pypi-config.allow-insecure-host`](#pypi-config) instead for more granular control.
+
+!!! note "Implementation detail and limitations"
+
+    For PyPI operations, since uv does not support a global TLS verification disable flag, pixi automatically adds all configured PyPI index hosts to the trusted hosts list when `tls-no-verify` is enabled. 
+    For the main PyPI index, `files.pythonhosted.org` (the download host) is also automatically added.
+    **Important limitation:** If your custom PyPI index redirects package downloads to a different host (e.g., a separate CDN or artifact server), that download host will not be automatically trusted, even with `tls-no-verify` set. 
+    In these cases, you *must* manually add the download host to [`pypi-config.allow-insecure-host`](#pypi-config).
+
 
 ```toml title="config.toml"
 --8<-- "docs/source_files/pixi_config_tomls/main_config.toml:tls-no-verify"
@@ -233,7 +243,7 @@ To setup a certain number of defaults for the usage of PyPI registries. You can
   `pixi init`.
 - `keyring-provider`: Allows the use of the [keyring](https://pypi.org/project/keyring/) python package to store and
   retrieve credentials.
-- `allow-insecure-host`: Allow insecure connections to host.
+- `allow-insecure-host`: A list of host names (without protocol or port) for which TLS certificate verification should be disabled when accessing PyPI registries. This is useful when working with internal PyPI mirrors that use self-signed certificates. For disabling TLS verification globally for all connections, use [`tls-no-verify`](#tls-no-verify) instead.
 
 ```toml title="config.toml"
 --8<-- "docs/source_files/pixi_config_tomls/main_config.toml:pypi-config"

src/assets/pixi/reference/pixi_manifest.md

@@ -173,7 +173,17 @@ Example:
 If `conda-forge` is not present in `conda-pypi-map` `pixi` will use `prefix.dev` mapping for it.
 
 ```toml
-conda-pypi-map = { "conda-forge" = "https://example.com/mapping", "https://repo.prefix.dev/robostack" = "local/robostack_mapping.json"}
+conda-pypi-map = { conda-forge = "https://example.com/mapping", "https://repo.prefix.dev/robostack" = "local/robostack_mapping.json"}
+```
+
+It is also possible to disable fetching external mpping by adding an empty map to the list
+
+```toml
+conda-pypi-map = { conda-forge = "map.json" }
+```
+
+```json title="map.json"
+{}
 ```
 
 ### `channel-priority` (optional)
@@ -235,7 +245,7 @@ solve-strategy = "lowest"
     [feature.one]
     solve-strategy = "lowest"
     [feature.two]
-    solve-strategy = "lowest-direct"    
+    solve-strategy = "lowest-direct"
     [environments]
     combined = ["two", "one"] # <- The solve strategy from feature `two` is used
     ```

src/assets/pixi/switching_from/conda.md

@@ -62,7 +62,7 @@ bat pixi.toml
 !!! warn "Never install `pip` with `pixi global`"
     Installations with `pixi global` get their own isolated environment.
     Installing `pip` with `pixi global` will create a new isolated environment with its own `pip` binary.
-    Using that `pip` binary will install packages in the `pip` environment, making it unreachable form anywhere as you can't activate it.
+    Using that `pip` binary will install packages in the `pip` environment, making it unreachable from anywhere as you can't activate it.
 
 
 ## Automated switching
@@ -80,7 +80,7 @@ You can import `environment.yml` files into a Pixi workspace — see our [import
 
 Encountering issues? Here are solutions to some common problems when being used to the `conda` workflow:
 
-- Dependency `is excluded because due to strict channel priority not using this option from: 'https://conda.anaconda.org/conda-forge/'`
+- Dependency `is excluded due to strict channel priority not using this option from: 'https://conda.anaconda.org/conda-forge/'`
   This error occurs when the package is in multiple channels. `pixi` uses a strict channel priority. See [channel priority](../advanced/channel_logic.md) for more information.
 - `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.