You said that the installation on Ubuntu is currently broken. Is this specific to WSL?

What I wrote in the PR description was based on watching a student try it on his computer 2 weeks. I can't test it myself.

Just now I tested the sagemath package on the ubuntu:jammy Docker image. It installs and tests OK as of today.

In any case, the Ubuntu package is stuck at version 9.5, so for this reason alone it should not be our primary recommendation.

You said that the installation on Ubuntu is currently broken. Is this specific to WSL?

What I wrote in the PR description was based on watching a student try it on his computer 2 weeks. I can't test it myself.

Just now I tested the sagemath package on the ubuntu:jammy Docker image. It installs and tests OK as of today.

In any case, the Ubuntu package is stuck at version 9.5, so for this reason alone it should not be our primary recommendation.

Thanks for the details. But this argument (especially your last point) applies to plain ubuntu as well. So I would prefer to simply change the how to install on ubuntu section to give priority to conda, and then leave the wsl section untouched.

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

That does not make much more sense either. The Linux section makes different recommendations based on the version of Sage that is found on the distribution.

The problem that I am solving here in this PR is that there are too many indirections, each of which can confuse our potential users. That's what "streamlining" means in the PR description.

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

That does not make much more sense either. The Linux section makes different recommendations based on the version of Sage that is found on the distribution.

The same would then also apply to Windows, as it is possible to use many different linux distros via wsl (as we also say in the docs).

This is not an interesting discussion.

Okay, let me see if I can summarize:

• Windows WSL has Ubuntu by default, and the very likely scenario on Windows is that people will not be using anything other than default.
• Apparently the Ubuntu version is stuck for some reason.
• Conda-forge (in some version) works
• So we should recommend this.

It will take me a little bit to test whether this actually works. But I do have access to a Windows computer if my son lets me on it 😄

However, I also don't want to get in the middle of the myriad meta-discussions going on around platforms etc. So I'm going to take the point of view that "Windows users probably need very explicit instructions, and shouldn't be asked to go to a scary Linux section" and not worry about Linux instructions, which however certainly might need updating as well.

Technical question: do we expect that once conda activate sage is done once, then sage will work (path etc.) from then on in? I know very little about conda.

So I'm going to take the point of view that "Windows users probably need very explicit instructions, and shouldn't be asked to go to a scary Linux section" and not worry about Linux instructions, which however certainly might need updating as well.

Yes, that's also my viewpoint here. If not for anything else, then certainly for keeping the focus of the PR as narrow as possible. After all, even with this deliberately narrow focus, it has been sitting for 3 weeks.

Technical question: do we expect that once conda activate sage is done once, then sage will work (path etc.) from then on in? I know very little about conda.

No, conda activate only affects the current shell session. To persist it, one would need to add the command to a shell initialization file such as .bash_profile

I'm setting it to blocker because it needs to make its way in the stable release.

I'll take a look once I get access to a Windows machine.

By the way, any sense on why the Ubuntu is stuck on such an old version? (Probably this was discussed ad nauseam elsewhere, sorry.)

I think maintainer burnout + possibly a problem with brial (hence #36380)

Removing blocker as there are problems with other PRs, see #37428 for more details.

How would this PR, 1 change to a documentation file, cause such a problem?

So this is interesting - at least on the most modern Windows, you actually don't have to install Ubuntu any more either. It just automatically chooses Ubuntu for you. (See here.) It also should automatically use WSL 2. So we may want to update that part (we should still remind users of older versions about those things, of course). I'll see about installing Sage now.

Additionally, you have to enable virtualization in BIOS. That could be annoying for some, and is definitely worth mentioning. (For instance, on my son's computer I had to just do this, otherwise I got errors when actually trying to start WSL.)

And then create a UNIX username and then restart shell after installing mamba ... wow, there are a lot of steps. Anyway, that's mostly documented in the Windows link. But the mamba thing is a little confusing because samba is default installed already, and a user might think there was a typo in the instructions.

It works!!! Though I can't figure out how to get plots to show up; any thoughts? I tried this link (which should totally be linked on the Windows install page ...) but it didn't seem to work.

Also, I'd still recommend pointing out other Linux options somehow, and streamlining the instructions to point out that most people will not need the Windows store now. Because your mileage may vary, and we don't want monolith instructions. Maybe for older Windows versions. But on this Windows 11 system, it worked.

Also, how fragile is this line?

mamba create -n sage sage python=3.11

Additionally, you have to enable virtualization in BIOS.

This is actually documented here but not in the basic instructions.

I'm putting needs work mostly because there are just enough tricky bits that simply saying "do this" isn't enough for a lot of users (notably the BIOS issue), as well as somewhat outdated (for most) like choosing the Ubuntu.

Also, I'd like to know if there is a good way to avoid the specific Python version reference, or to automatically update it when necessary.

But in principle the conda piece works fine, which is presumably the main point.

@kcrisman Many thanks for testing and the detailed suggestions.

at least on the most modern Windows, you actually don't have to install Ubuntu any more either. It just automatically chooses Ubuntu for you. (See here.) It also should automatically use WSL 2. So we may want to update that part (we should still remind users of older versions about those things, of course).

I've updated the steps and links to refer to these streamlined instructions, please take a look.

And then create a UNIX username

I've added this step

Additionally, you have to enable virtualization in BIOS.

This is actually documented here but not in the basic instructions.

I've added this now (in 23e1b42)

Though I can't figure out how to get plots to show up; any thoughts? I tried this link (which should totally be linked on the Windows install page ...) but it didn't seem to work.

I've just cut out the outdated Docker/WSL stuff from that wiki page and replaced it by a link the Sage installation guide.

I don't know if it makes sense to work on the plotting support instructions that are provided there, or we should just delete them.
I'd rather guide people to getting Jupyter notebooks running.
A later installation guide section has this:

• https://deploy-livedoc--sagemath.netlify.app/html/en/installation/launching#wsl-post-installation-steps

I have merged #37588 (thanks @williamstein for testing that) and updated the instructions from there.

I'm setting back to "blocker" because this really should be merged in 10.3.

@kcrisman With these changes merged, do you want to test again, or can we merge?

I'm posting to record a vote of -1 on behalf of Tobias Diez.

Tobias added the "disputed" label and has requested that it be removed, so I am doing so. Also, based on the policy stated at https://groups.google.com/g/sage-devel/c/XDvKkMRoDk4/m/0yrtdKkGAwAJ, "if there is disagreement about whether a PR should be marked as a blocker, mark it as critical instead." So I am marking this as critical.

How can there be a vote if the PR is not "disputed" any more?

In my opinion, if it's not disputed, "-1" votes have no clear impact, other than to let developers know that someone has some objections.

@kcrisman With these changes merged, do you want to test again, or can we merge?

Ideally someone should test again, though William's other testing is good. I just worry about Windows being wonky. However, I do vote +1 for this change overall, to be clear.

Comments on testing:

• It does ask a few questions in the install process for miniforge, so one might want to note that in the instructions (specifically when running the bash script), since Windows users may not be used to text license questions and typing "yes" 😄
• Still no one has answered my question about whether the Python 3.11 is brittle. How often will that have to be updated? Is there a version-agnostic way to do that?
• Even with an existing mambaforge, it worked fine installing Sage with miniforge instead, it was "smart enough" to ask questions. So the actual instructions are fine, and 2+2=4.
• Finally, I think the user should be notified in these instructions (again, thinking of absolute newbies) that sage -n will give a notebook, but they may have to copy and paste the link given in the command line. I don't know if that belongs in one of these files (maybe after "You can now start SageMath as follows:"), but I think it's important. (Until a "WSL launcher app" shows up, that would be cool too!)

Addressing the issue implicitly raised, this comment suggests that, while Tobias is currently voting -1 due to duplication, it might just as easily be possible to have a quick followup PR that then uses some standard rst tool to remove that duplication. I don't really care if it happens here or there, but it does seem helpful in terms of preventing doc rot.

• no one has answered my question about whether the Python 3.11 is brittle. How often will that have to be updated? Is there a version-agnostic way to do that?

Sorry for missing this.
That it is written there explicitly -- instead of referring the reader to go elsewhere to look for this information -- is to serve the reader.

Keeping the documentation source a simple .rst file (instead of generating it somehow from some template file so that we could refer to a variable) -- this is to keep the structure of our documentation sources as simple and straightforward as possible -- this serves the contributors to the documentation.

The cost of this (= the cost of updating this occurrence) is low, as the update happens only about once a year, and the places to change are easy to find, in particular for those who know how to make the updates of the supported Python versions.

Tobias is currently voting -1 due to duplication

FWIW, I recommend not to take such rationalizations at face value.

• It does ask a few questions in the install process for miniforge, so one might want to note that in the instructions (specifically when running the bash script), since Windows users may not be used to text license questions and typing "yes"

Done in d3a2a16

• I think the user should be notified in these instructions (again, thinking of absolute newbies) that sage -n will give a notebook, but they may have to copy and paste the link given in the command line. I don't know if that belongs in one of these files (maybe after "You can now start SageMath as follows:"), but I think it's important.

Done in 4eacb7b, please take a look.

Documentation preview for this PR (built with commit 4eacb7b; changes) is ready! 🎉

Thanks for addressing all these concerns. While I still hope for an nth iteration of a double click installer, this is fairly painless as such things go in our Windows ecosystem experience.

@kcrisman Thanks for the review!

@vbraun Please merge. Can't set to blocker because policy.