My 5 minutes looking up uv and pixi is that they are just wrapping conda - do we need to specify the syntax here? Aren't there a bunch of other tools that do the same thing? Why are we choosing these two, particularly if one of them doesn't work without an additional install?

@jklymak uv and pixi are not wrapping conda. They are new package and environment managers. They are significantly superior than existing solutions. uv is targeting python-only systems, replacing pip+venv. pixi is "conda done right". I project that these two tools will dominate the python package/environment in the coming years. There are other tools (rye, poetry, ...) that have gained some traction in the past, but nowhere near as much as uv/pixi. We should mention the tools that people are/will be using predominantly.

Note that numpy is even recommending pixi/uv for new users https://numpy.org/install/. I don't think we as a project need or should go that far (people will likely already have made a decision on their package tooling when they come to us).

On a side note, I recommend you to have a look at these new tools, pixi if you are currently using conda, uv if you are using pip+venv.

Certainly numpys support indicates that this may stick around. I'm a little surprised numpy is suggesting pixi for new users as it is quite a different paradigm from environments (if I understand correctly)

Yes, it is a different paradigm, but IMHO better once you've let go from the idea of isolated environments. The environment idea is an extension of your classical system installation (install something and then its available on your computer) in that you want to have multiple independent installations. The project-based approach moves the dependencies and execution context closer to the code/app/repo. Instead of switching to an environment and then working in that environment, you simply run the code in it's predefined context. Note you can still open a shell with the environment activated if needed (which I sometimes do, because I also cannot let go of my environment-based thinking yet).

@tacaswell have I represented the uv issue appropriately?

Yes, it is a different paradigm, but IMHO better once

yes agreed - it looks like a great paradigm. But maybe I'm slow, it took me a fair bit of reading pixi's own documentation before I understood why typing pixi python my script.py was better than activating an environment. I've not tried it yet, but I'm still not sure what happens when choosing a Jupyter kernel if using jlab (jupyterlab/jupyterlab-desktop#834) or vscode (looks like maybe this works: microsoft/vscode-jupyter#16335). But perhaps none of this is our concern.

I have subscribed to astral-sh/uv#6893.

As explained in the original message:

(i) I think we should have one install command written out that has a working interactive backend

It's non-trivial to know what package to install to get a working backend.

I'm suggesting being more general, not more specific. "Some installations do not include a working interactive backend on all platforms, so additional dependencies like pyside or qtagg should be installed as well and specified as default in your matplotlibrc. See backend selection for details".

IMHO this is too vague. The install instruction should contain a command that leads to a reasonable usable installation. People tend to overlook additional textual remarks. If we only had uv add matplotlib with your comment, I bet many would still just execute the command. While you could argue it's their fault if they don't read the comments, (i) we should use visual guidance appropriately and (ii) failing to do so will fall back on us though bug reports.

Visual guidance: we should not have a single formatted install command if that's not what people should typically use. Alternatives are

• no install command, which is viable, but sort of defeats the purpose of install instructions
• a single specific install command like uv add matplotlib pyside6. I don't like this because if people only use notebooks, the simple version is actually sufficient and suggesting installing a gui framework is over board there.
• therefore, I chose to have the two commands, which signals immediately that there are different cases and people need to decide what they need.

Sure that's one approach. But the advice to explicitly install a backend is one we often tell people to use when there is a problem opening a GUI. If someone does uv install matplotlib and they can't open a GUI window for whatever reason then they presumably can read the extra text. Whereas if we do as you are suggesting here they will just blindly install pyside whether they need it or not.

If someone does uv install matplotlib and they can't open a GUI window for whatever reason then they presumably can read the extra text.

That's exactly what I want to prevent. People should not end up with an initially broken environment. With the proposal here:

We still have uv add matplotlib as the reasonable baseline (e.g. for jupyter only users), but we have a pronounced warning that this is not suitable for all cases and a concrete suggestion what to do if you use figure windows.

If you feel very strong on this, we could leave out the concrete suggestion here, but then, you should add concrete documentation on how to install the gui backends (i.e. package names) in the linked documentation.

Note also that the conda package matplotlib defines pyside6 as a dependency. So the suggestion is similar to what happens in the conda world (there's matplotlib-base if you don't want that dependency). In that sense I could also live with uv add matplotlib pyside6 as the default recommendation and add a note below that pyside6 can be left out if you know you don't need it`.

I don't feel strongly, just suggesting that this happens other times with pip and Tk not working on some platforms. therefore a more general solution might be nicer.

Given the subtleties of all our backends I do t think it's crazy that we have a bare "uv add Matplotlib" and a separate section below on "if you require an interactive backend we suggest you install pyside using the same package manager" (but with more words and links). It's an opportunity to explain a bit about the difference between notebooks and commmand line, and point into the docs. We aren't numpy where our stuff just works, so a bit of a longer install description seems called for.

I don't feel strongly, just suggesting that this happens other times with pip and Tk not working on some platforms. therefore a more general solution might be nicer.

AFAIK, Tk not working on other platforms happens but is rare - otherwise we'd see much more bug reports on this. The difference with uv is that it won't work for a significant number of users, which warrants better guidance for them.

My premise on the install section on the main page is that using the commands given there should generally result in a usable installation of matplotlib. Therefore, only stating uv add matplotlib won't be a good servive to our users. The solution proposed here, i.e. adding a warning including one conrete solution, is as far as I can stretch uv add matplotlib while maining that premise.

The only alternative I see is beeing more opinionated by default, with the generalization in an accompanying note:

uv add matplotlib pyside6

Note: Adding pyside6 ensures that you have a GUI framework installed so that you can display figures windows. You may leave this out if you don't show figure windows (e.g. only work in notebooks or use matplotlib to create image files). Alternatively, you can also install other supported GUI frameworks](link).

I'm explicitly against

uv add matplotlib

[a block of text explaining that you need a GUI framework to get plots in a window]

Sure - well I won't block. But I think a more complex install calls for more complex instructions.

Would it be worth adding optional dependency groups for us? matplotlib[qt,cairo,...] so it is clear that it is optional on our side?

AFAIK there are two separate things, optional dependencies PEP-621 and dependency groups PEP-735. See also astral-sh/uv#9011 (comment).

Yes I believe this is worth looking into (and I think optional dependencies is what we want).

Edit: But this is kind of independent of this PR. I plan to backport this to 3.10-doc, and there we don't have the optional dependencies yet. So the initial version will have to do without.

The most important difference is that that uv only uses wheels/sdists whereas pixi uses conda(-forge) packages by default but can pull wheels/sdists from pypi if needed. You can put ~anything in a wheels (see #29740 ) so it is not fair to say uv is "python only", but there are some serious technical and social issues with wheels (see https://pypackaging-native.github.io and fiasco with the windows wheels last year).

Both are written in rust (for the solvers + system I/O work to unpack install), are really smart about caching, and are fast. Both are project based and include the notion of tasks that have dependencies. They both also provide a lock files (that you can check into VC) that really solve the problem of "it worked on my machine" by making it easry to get the exact same env on another system (pixi also has some really nifty solve rules for linked environments + will simultaneously solve for mac + win + linux).

I've started using pixi for some BNL stuff and have been super happy. Unrelated to the docs changes we should probably start using it for dev work (I have a strong hope that it will make the docs build on windows "just work").

I agree that pixi and/or uv are very likely going to dominate the Python packaging landscape for the next 5 years or so and we should start to point our users at them.

It might be worth naming python-build-standalone in the note (I made a suggestion). uv can work with what ever Python it finds so if it grabs system Python it may very well work, the only issue is if you ask uv to install Python for you.

I agree to go with pyside6 over pyqt. We recently switched the conda-forge dependency to pysides. Historically I have found pyqt more Pythonic, but given the license and that pysides is maintained by the same people as Qt it is compelling to switch.

Let's start with this. We can always improve later.