docs: refactor getting started and python tutorial (#3977)

Author: ruben-arts

docs/first_project.md

@@ -0,0 +1,153 @@
+# Making a Pixi project
+
+Pixi's biggest strength is its ability to create reproducible powerful and flexible projects.
+Let's go over the common steps to create a Pixi project.
+
+## Creating a Pixi project
+To create a new Pixi project, you can use the `pixi init` command:
+
+```shell
+pixi init my_project
+```
+
+This command creates a new directory called `my_project` with the following structure:
+
+```shell
+my_project
+├── .gitattributes
+├── .gitignore
+└── pixi.toml
+```
+
+The `pixi.toml` file is the manifest of your Pixi project.
+It contains all the information about your project, such as its channels, platforms, dependencies, tasks, and more.
+
+The one created by `pixi init` is a minimal manifest that looks like this:
+
+```toml title="pixi.toml"
+[workspace]
+authors = ["Jane Doe <[email protected]>"]
+channels = ["conda-forge"]
+name = "my_project"
+platforms = ["osx-arm64"]
+version = "0.1.0"
+
+[tasks]
+
+[dependencies]
+```
+
+??? 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.
+    Install the Even [Better TOML VSCode](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension to get the best experience.
+    Or use the integrated schema support in PyCharm.
+
+## Managing dependencies
+After creating the project, you can start adding dependencies to the project.
+Pixi uses the `pixi add` command to add dependencies to the project.
+This command will , by default, add the **conda** dependency to the `pixi.toml`, solve the dependencies, write the lockfile and install the package in the environment.
+For example, lets add `numpy` and `pytest` to the project.
+
+```shell
+pixi add numpy pytest
+```
+This results in these lines being added:
+
+```toml title="pixi.toml"
+[dependencies]
+numpy = ">=2.2.6,<3"
+pytest = ">=8.3.5,<9"
+```
+
+You can also specify the version of the dependency you want to add.
+
+```shell
+pixi add numpy==2.2.6 pytest==8.3.5
+```
+
+### PyPI dependencies
+Pixi normally uses `conda` packages for dependencies, but you can also add dependencies from PyPI.
+Pixi will make sure it doesn't try to install the same package from both sources, and avoid conflicts between them.
+
+If you want to add them to your project you can do that with the `--pypi` flag:
+
+```shell
+pixi add --pypi requests
+```
+This will add the `requests` package from PyPI to the project:
+
+```toml title="pixi.toml"
+[pypi-dependencies]
+requests = ">=2.31.0,<3"
+```
+
+## Lockfile
+Pixi will always create a lockfile when the dependencies are solved.
+This file will contain all the exact version of the packages and their dependencies.
+Resulting in a reproducible environment, that you can share with others or use for testing and deployment.
+
+The lockfile is called `pixi.lock` and it is created in the root of the project.
+It contains all the information about the dependencies, such as their versions, channels, platforms, and more.
+
+```yaml title="pixi.lock"
+version: 6
+environments:
+  default:
+    channels:
+    - url: https://prefix.dev/conda-forge/
+    indexes:
+    - https://pypi.org/simple
+    packages:
+      osx-arm64:
+      - conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda
+      - pypi: ...
+packages:
+- conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda
+  sha256: adfa71f158cbd872a36394c56c3568e6034aa55c623634b37a4836bd036e6b91
+  md5: fc6948412dbbbe9a4c9ddbbcfe0a79ab
+  depends:
+  - __osx >=11.0
+  license: bzip2-1.0.6
+  license_family: BSD
+  size: 122909
+  timestamp: 1720974522888
+- pypi: ...
+```
+
+## Managing tasks
+Pixi has a built-in cross-platform task runner that allows you to define tasks in the manifest.
+This is a great way to share tasks with others and to ensure that the same tasks are run in the same environment.
+The tasks are defined in the `pixi.toml` file under the `[tasks]` section.
+
+You can add one to your project by running the `pixi task add` command.
+
+```shell
+pixi task add hello "echo Hello, World!"
+```
+This will add the following lines to the `pixi.toml` file:
+
+```toml title="pixi.toml"
+[tasks]
+hello = "echo Hello, World!"
+```
+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 environment.
+
+## Environments
+Pixi always creates a virtual environment for your project.
+These environments are located in the `.pixi/envs` directory in the root of your project.
+
+Using these environments is as simple as running the `pixi run` or `pixi shell` command.
+These commands will automatically activate the environment and run the command in it.
+
+```shell
+pixi run python -VV
+# or:
+pixi shell
+python -VV
+exit
+```

docs/getting_started.md

@@ -1,112 +1,106 @@
-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`.
+# Basic usage of Pixi
 
-```toml title="pixi.toml"
---8<-- "docs/source_files/pixi_workspaces/introduction/task_add/pixi.toml"
-```
+Pixi can do alot of things, but it is designed to be simple to use.
+Let's go through the basic usage of Pixi.
 
-`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](./workspace/lockfile.md).
+## Managing workspaces or projects
 
+- [`pixi init`](./reference/cli/pixi/init.md) - create a new Pixi manifest in the current directory
+- [`pixi add`](./reference/cli/pixi/add.md) - add a dependency to your manifest
+- [`pixi remove`](./reference/cli/pixi/remove.md) - remove a dependency from your manifest
+- [`pixi update`](./reference/cli/pixi/update.md) - update dependencies in your manifest
+- [`pixi upgrade`](./reference/cli/pixi/upgrade.md) - upgrade the dependencies in your manifest to the latest versions, even if you pinned them to a specific version
+- [`pixi lock`](./reference/cli/pixi/lock.md) - create or update the lockfile for your manifest
+- [`pixi info`](./reference/cli/pixi/info.md) - show information about your workspace
+- [`pixi run`](./reference/cli/pixi/run.md) - run a task defined in your manifest or any command in the current environment
+- [`pixi shell`](./reference/cli/pixi/shell.md) - start a shell in the current environment
+- [`pixi list`](./reference/cli/pixi/list.md) - list all dependencies in the current environment
+- [`pixi tree`](./reference/cli/pixi/tree.md) - show a tree of dependencies in the current environment
+- [`pixi clean`](./reference/cli/pixi/clean.md) - remove the environment from your machine
 
-## 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!
+## Managing global installations
+Pixi can manage global installations of tools and environments.
+It installs the environments in a central location, so you can use them from anywhere.
 
-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"
---8<-- "docs/source_files/pixi_workspaces/introduction/multi_env/pixi.toml"
-```
+- [`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 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 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:
+More information: [Global Tools](./global_tools/introduction.md)
 
-!!! warning
+## Running one-off commands
+Pixi can run one-off commands in a specific environment.
 
-    This written out for demonstration purposes.
-    Don't spell "default" out like this in your own manifest, Pixi will do it for you behind the scenes.
+- [`pixi exec`](./reference/cli/pixi/exec.md) - run a command in a temporary environment.
+- [`pixi exec --spec`](./reference/cli/pixi/exec.md#arg---spec)   - run a command in a temporary environment, with a specific specification.
 
-```toml
-[workspace]
-channels = ["conda-forge"]
-name = "hello-world"
-platforms = ["linux-64", "osx-arm64", "win-64"]
-
-# [tasks] belong to the default feature
-[feature.default.tasks]
-start = 'python hello.py'
-
-# [dependencies] belong to the default feature
-[feature.default.dependencies]
-cowpy = "1.1.*"
-
-[feature.py312.dependencies]
-python = "3.12.*"
-
-[feature.py313.dependencies]
-python = "3.13.*"
-
-[environments]
-# Pixi automatically creates a default environment that consists only of the default feature
-default = ["default"]
-# Unless you opt-out with `no-default-feature`, every environment contains the default feature
-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:
+For example:
 
 ```bash
-pixi run --environment=py312 start
+> pixi exec python -VV
+Python 3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:24:05) [Clang 18.1.8 ]
+> pixi exec --spec "python=3.12" python -VV
+Python 3.12.11 | packaged by conda-forge | (main, Jun  4 2025, 14:38:53) [Clang 18.1.8 ]
 ```
 
-```
- _________________________
-< Hello from Python 3.12! >
- -------------------------
-     \   ^__^
-      \  (oo)\_______
-         (__)\       )\/\
-           ||----w |
-           ||     ||
-```
+## Multiple environments
+Pixi workspaces allow you to manage multiple environments.
+An environment is build out of one or multiple features.
 
-And we can run this command to try it with Python 3.13:
+- [`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
+- [`pixi workspace environment add`](./reference/cli/pixi/workspace/environment/add.md) - add an environment to the workspace
+- [`pixi run --environment`](./reference/cli/pixi/run.md#arg---environment) - run a command in a specific environment
+- [`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)
 
-```bash
-pixi run --environment=py313 start
-```
+## Tasks
+Pixi can run cross-platform tasks using it's built-in task runner.
+This can be a predefined task or any normal executable.
 
+- [`pixi run`](./reference/cli/pixi/run.md) - Run a task or command
+- [`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
+```toml title="pixi.toml"
+[tasks]
+build = "make build"
+# using the toml table view
+[tasks.test]
+cmd = "pytest"
+depends-on = ["build"]
 ```
- _________________________
-< Hello from Python 3.13! >
- -------------------------
-     \   ^__^
-      \  (oo)\_______
-         (__)\       )\/\
-           ||----w |
-           ||     ||
-```
+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.
+
+- [`pixi add --platform`](./reference/cli/pixi/add.md#arg---platform) - add a package only to a specific platform
+- [`pixi workspace platform add`](./reference/cli/pixi/workspace/platform/add.md) - add a platform to the workspace that you want to support with your project
+
+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.
+- [`pixi config`](./reference/cli/pixi/config.md) - Show or edit the Pixi configuration.
+- [`pixi tree`](./reference/cli/pixi/tree.md) - Show a tree of dependencies in the current environment.
+- [`pixi list`](./reference/cli/pixi/list.md) - List all dependencies in the current environment.
+- [`pixi clean`](./reference/cli/pixi/clean.md) - Remove the project environments from your machine.
+- `pixi help` - Show help for Pixi commands.
+- `pixi help <subcommand>` - Show help for a specific Pixi command.
+- [`pixi auth`](./reference/cli/pixi/auth.md) - Manage authentication for conda channels.
+- [`pixi search`](./reference/cli/pixi/search.md) - Search for packages in the configured channels.
+- [`pixi completion`](./reference/cli/pixi/completion.md) - Generate shell completion scripts for Pixi commands.
 
 
 ## Going further

docs/installation.md

@@ -1,3 +1,4 @@
+# Installation
 To install `pixi` you can run the following command in your terminal:
 
 === "Linux & macOS"
@@ -35,7 +36,9 @@ Now restart your terminal or shell to make the installation effective.
     You can check the installation `sh` script: [download](https://pixi.sh/install.sh) and the `ps1`: [download](https://pixi.sh/install.ps1).
     The scripts are open source and available on [GitHub](https://github.com/prefix-dev/pixi/tree/main/install).
 
-
+!!! note "Don't forget to add autocompletion!"
+    After installing Pixi, you can enable autocompletion for your shell.
+    See the [Autocompletion](#autocompletion) section below for instructions.
 ## Update
 
 Updating is as simple as installing, rerunning the installation script gets you the latest version.
@@ -213,3 +216,22 @@ Add the following to the end of `~/.elvish/rc.elv`:
 
 eval (pixi completion --shell elvish | slurp)
 ```
+
+# Uninstall
+Before un-installation you might want to delete any previous files pixi has installed.
+
+1. Remove any cached data:
+    ```shell
+    pixi clean cache
+    ```
+2. Remove the environments from your pixi projects:
+    ```shell
+    cd path/to/project && pixi clean
+    ```
+3. Remove the `pixi` and it's global environments
+    ```shell
+    rm -r ~/.pixi
+    ```
+4. Remove the pixi binary from your `PATH`:
+   - For Linux and macOS, remove `~/.pixi/bin` from your `PATH` in your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`).
+   - For Windows, remove `%UserProfile%\.pixi\bin` from your `PATH` environment variable.