Skip to content

enh: Revise Pixi subsection in package dependency section #587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+26 −51
Open

enh: Revise Pixi subsection in package dependency section #587

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 26 additions & 51 deletions package-structure-code/declare-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,10 +406,8 @@ dependencies = [


:::{todo}
### Using conda and pixi
### Using conda and Pixi

::::{todo}
Ask Matthew to review this section...
:::

The `pyproject.toml` file works great for pure-Python packages. However,
Expand All @@ -423,64 +421,41 @@ You can maintain an `environment.yml` file to help users and contributors
set up conda environments. This is especially useful for packages with
system-level dependencies like GDAL.

**Consider pixi for conda workflows:**
**Consider Pixi for conda package focused workflows:**
Copy link
Author

@matthewfeickert matthewfeickert Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"conda" -> "conda package focused" as "conda" as a term historically gets overused in ways that are clear to experienced users who know how to fuzzy-match "conda" to whatever term makes sense in context of the ecosystem of conda tooling. To new users having explicit language can be helpful.

(This is an ongoing complaint I have with a lot of the conda — the tool — documentation in general.)


[Pixi](https://pixi.sh) is a modern package manager built on top of both
Copy link
Author

@matthewfeickert matthewfeickert Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this whole subsection is meant to be short, so if I have expanded this too much it should just get squashed back down and then a whole section on Pixi should be added later.

the conda and Python package ecosystems.
Pixi is able to treat conda and Python package requirements with parity when
resolving environments, but uses a "conda-first" approach of using already
resolved conda packages if possible when resolving Python dependencies.
Comment on lines +428 to +430
Copy link
Author

@matthewfeickert matthewfeickert Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As is this might not be clear. What I'm trying to convey is that you do

pixi init example && cd example
pixi add numpy
pixi add --pypi scipy

generating

[workspace]
channels = ["conda-forge"]
name = "example"
platforms = ["linux-64"]
version = "0.1.0"

[tasks]

[dependencies]
numpy = ">=2.3.4,<3"

[pypi-dependencies]
scipy = ">=1.16.3, <2"

Pixi will get only scipy from PyPI and will use everything else from conda-forge

$ pixi list | grep 'numpy\|scipy'
numpy             2.3.4      py314h2b28147_0       8.5 MiB    conda  https://conda.anaconda.org/conda-forge/
scipy             1.16.3                           112.9 MiB  pypi   scipy-1.16.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Pixi [can also use `pyproject.toml` for configuration](https://pixi.sh/latest/python/pyproject_toml/).
If your project relies heavily on conda packages, Pixi offers a streamlined
workflow with faster dependency resolution and automatic lock file support for
full environment reproducibility.
If you already have an existing conda environment definition file, like
an `environment.yml`, you can
[import the environment](https://pixi.sh/latest/tutorials/import/) into a new
Pixi workspace with

[Pixi](https://pixi.sh) is a modern package manager built on conda that
uses `pyproject.toml` for configuration. If your project relies heavily
on conda packages, pixi offers a streamlined workflow with lockfiles and
faster dependency resolution.
```
pixi init --import environment.yml
```
Comment on lines +435 to +442
Copy link
Author

@matthewfeickert matthewfeickert Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is of interest here, or should be moved to another section to expand out later.


:::{admonition} A note for conda users
:class: tip

If you use a conda environment for development and install your package
with `python -m pip install -e .`, dependencies will be installed from
PyPI rather than conda. This can cause conflicts, especially for packages
with system dependencies.
with `python -m pip install -e .` dependencies will be installed from PyPI,
potentially overwriting conda packages that had already been installed.
This can cause conflicts, especially for packages with system dependencies.

To avoid this, install your package without dependencies:
`python -m pip install -e . --no-deps`

Then install dependencies through your conda environment.yml file.
:::
::::

### Using conda and pixi

:::{todo}
Ask matthew to review this section...
:::

The `pyproject.toml` file works great for pure-Python packages. However,
some packages (particularly in the scientific Python ecosystem) require
dependencies written in other languages like C or Fortran. Conda was
created to support the distribution of tools with non-Python dependencies.

**For conda users:**

You can maintain an `environment.yml` file to help users and contributors
set up conda environments. This is especially useful for packages with
system-level dependencies like GDAL.

**Consider pixi for conda workflows:**

[Pixi](https://pixi.sh) is a modern package manager built on conda that
uses `pyproject.toml` for configuration. If your project relies heavily
on conda packages, pixi offers a streamlined workflow with lockfiles and
faster dependency resolution.

:::{admonition} A note for conda users
:class: tip

If you use a conda environment for development and install your package
with `python -m pip install -e .`, dependencies will be installed from
PyPI rather than conda. This can cause conflicts, especially for packages
with system dependencies.

To avoid this, install your package without dependencies:
`python -m pip install -e . --no-deps`
```
python -m pip install -e . --no-deps
```
Comment on lines +454 to +456
Copy link
Author

@matthewfeickert matthewfeickert Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Emphasize the behavior you want users to adopt with a code block, which also gives it a copy button.


Then install dependencies through your conda environment.yml file.
Then install dependencies through your conda `environment.yml` file.
:::

## Dependencies in Read the Docs
Expand Down