Documentation for using WSL2 on Windows

[hyamanieu]

Issue Report

Issue Description

I wanted to suggest additional information on setting up Spyder on Microsoft Windows when combined with WSL2. Setting up Spyder on WSL as suggested by https://github.com/spyder-ide/spyder/issues/13023 is an overkill. One can develop with the normal Windows-based installation of spyder and if necessary link to a spyder kernel running on the subsystem linux.

I can submit a PR, but I'm not sure where to put it: FAQ of the spyder wiki? The installer documentation?

Where is the relevant portion of the documentation located?

I would put it just before this chapter https://github.com/spyder-ide/spyder-docs/blob/master/doc/installation.rst#development-builds, but maybe it's too specific to land there.

What would you suggest it be replaced with?

Using WSL2 on Windows

If you already installed Spyder on your Windows machine, you do not need to reinstall it on a WSL2-based Linux machine if your code must run there.

Windows creates a path on your network to the partitions of your Linux machine located at \\wsl$. You must map a network drive, e.g. W:, for Spyder to correctly go through the files and folders of your virtual machine.

Should you have installed a conda or virtual environment on your Linuxmachine, Spyder can be pointed to its python interpreter after installing spyder-kernels.

Other information

• Is the problem specific to documentation for a particular version of Spyder? No

• Are you planning on submitting a Github pull request with a suitable change? If indicated where.

• Anything else you'd like to add? No

[CAM-Gerlach]

Hey @hyamanieu , thanks so much for offering your contribution. This sounds like quite useful information to add to Spyder's docs, and your section seems to be carefully thought out, clear and well written.

We could put it in the install guide, but like you say, its pretty specific to have its own top-level section there. Instead, I think it may be a great fit for the purpose and format of our FAQ page; it should be much easier to find as a top-level question there in the "Install" section rather than near the bottom of the install guide, and the length and focus of the content is just right for an FAQ answer.

I'd suggest putting it right below the first question, "How do I install Spyder", as it at least nominally extends that question to cover a specific case. To avoid a potential merge conflict, I suggest targeting master (we may be able to backport it later). Finally, it would be great to have a couple sentences at least briefly describing how to install spyder-kernels and point Spyder to it (unfortunately, we don't currently have a single specific question that concisely explains that, otherwise you could just link to it).

Here's an idea of how to reframe what you wrote as a FAQ question, formatted it as RST following our guidelines, adding the above explanation and a reference to our troubleshooting guide. Feel free to use it as-is or as a starting point, and don't hesitate to reply on this issue if you have further questions or anything we can help you with. Thanks again.

.. dropdown:: Q: How do I install Spyder on Windows Subsystem for Linux 2 (WSL2)?
   :container: + dropdown-id-install-wsl2

   If you already installed Spyder on your Windows machine, you do not need to reinstall it on a WSL2-based Linux environment if your code must run there.

   Instead, just install `Miniconda`_ inside WSL2 and create a new conda environment (or use an existing conda- or virtualenv), then install Spyder-Kernels into that environment with e.g. ``conda install spyder-kernels``.
   Make sure to note the path to the environment's Python interpreter, which you can find by running ``python -c "import sys; print(sys.executable)"``.

   Finally, under :menuselection:`Python interpreter --> Use the following Python interpreter` in Spyder's preferences, navigate to the path above inside your WSL2 environment, apply changes and restart the kernel in the :doc:`panes/ipythonconsole`.

   If the kernel fails to start, see :ref:`starting-kernel-problems-ref` in our troubleshooting guide for help.

   .. note::

      Windows creates a network path located at ``\\wsl$`` that points to the partitions of your WSL2 environment.
      You **must** map a network drive letter to this path, e.g. ``W:``, for Spyder to correctly see the files and folders of your virtual machine.

[hyamanieu]

I was a bit hasty: it's not that straightforward to connect to a python kernel, connection to an external kernel must be used so it must first be started on WSL.

I'll try to document it as you advised.

By the way, https://docs.spyder-ide.org/ipythonconsole.html#connect-to-an-external-kernel is a deadlink :)

[CAM-Gerlach]

Thanks, and great catch; I should have asked about that before, sorry.

I see you linked a PR over on your fork (did you mean to make that here instead)? Your work looked great; the steps you added were clear and explicit while still being concise. We look forward to seeing it submitted over here whenever you are ready to do so.

I might suggest a few changes to your commands and some nitpicky technical fixes to the reST syntax and formatting per our style guide. If and only if you'd like to invite me to, I can make a PR on your fork against your branch with these changes, which you can then review and merge as you see fit, but that's totally up to you. Otherwise, you are welcome to fix the critical blockers yourself, and the rest we can address after your PR here is merged.

As a tip, make sure to install and run our pre-commit hooks as described in the contributing guidelines; they catch and in most cases automatically fix many common technical and style issues that will cause the CI checks to error out (including things like making sure to your commit messages are descriptive and in the imperative, e.g. "Add FAQ question about installing Spyder on WSL2").

By the way, https://docs.spyder-ide.org/ipythonconsole.html#connect-to-an-external-kernel is a deadlink :)

Oh, thanks, where did you see that specifically? The up to date link is https://docs.spyder-ide.org/current/panes/ipythonconsole.html#using-external-kernels or more specifically (for remote kernels) https://docs.spyder-ide.org/current/panes/ipythonconsole.html#connect-to-a-remote-kernel . You can link directly to this section from your FAQ question with :ref:`connecting-external-kernel`.

[CAM-Gerlach]

Sidenote for @ccordoba : Seems like the issue with ipython_genutils (which should be installed via conda rather than pip to avoid breaking the environment) might be something we should address; the package is described in strong terms as something that should not be depended upon by other projects, whose usage should be removed as soon as practical and which will be removed soon. IPython 7.0 no longer requires it, though apparently ipykernel apparently does (but it is not installed by default when I test-install. Seems related to spyder-ide/spyder-kernels#323 . Anything we can/should do about this?

[hyamanieu]

Yes you can work on my branch.

I was just limited on time, I didn't pay much attention to where I was submitting my pr.

I'll try to find some time to do what you said.

Note the dead link I mentioned is in the accompanying text of the modal window opening when you click on "connect to an existing kernel".

Also installing with pip will not break the environment. It works just fine to me. This environment is not Spyder's but just the work one on wsl. It just wasn't in the main conda channel.

[CAM-Gerlach]

Yes you can work on my branch.

Okay, thanks. I opened a PR on your repo with the tweaks.

I was just limited on time, I didn't pay much attention to where I was submitting my pr.

No worries, happens to all of us.

I'll try to find some time to do what you said.

If you're short on time, don't worry about the pre-commit hooks or anything else further. Your work is very well done and should be ready to go as-is, at least from my end, as the minor tweaks in the PR I submitted to your branch include fixes for all the pre-commit issues. Unless the others have further comments, once that's merged in to your branch, the only thing you would need to do is just submit a PR to this repo by clicking this link.

Note the dead link I mentioned is in the accompanying text of the modal window opening when you click on "connect to an existing kernel".

Ah, gotcha. Thanks so much for the catch. I've opened a PR spyder-ide/spyder#16540 to fix this.

Also installing with pip will not break the environment. It works just fine to me.

Right, it may not break right away, but it has a good chance to in the future if users already have, or later on install/update anything that depends on it, such as slightly less up to date versions of IPython, Juptyer notebook/lab, ipykernels, etc., due to shadowing and dep conflicts (especially for users less astute, careful and experienced as yourself). Based on the countless times we've encountered it helping other users over the years, our FAQ questions, guides and tutorial videos all warn strongly against this.

This environment is not Spyder's but just the work one on wsl. It just wasn't in the main conda channel.

I tested installing it from both defaults and conda-forge in a clean env with cleared cache on both Windows and Linux and wasn't able to reproduce any issues, and per conda.org its still available in both channels. So I'm not certain what you ran in to; we can investigate further for you if you wouldn't mind sharing your conda list of the environment you attempted to install it in, exactly what conda command you tried and the full output you got. Thanks.

[hyamanieu]

I made the PR with your inputs! Also I don't know what went wrong when I tried to run conda install ipython_genutils, but it now works.

Thanks for the tremendous help and the detailed responses each time :) . I need to learn Sphinx so I can better help next time.

[CAM-Gerlach]

Thanks so much @hyamanieu , amazing work and we can't wait to merge it. I approved the PR you just submitted and it should be ready to go, pending any last comments from @juanis2112 . When it's ready to merge, I'll squash my commits in.

Huh, dunno. Let us know if you have further problems with it.

Of course, more than happy to—its what we're here for. It was just a few pointers here and taking care of a bunch of tiny formatting nitpicks. Thanks so much for your great work and being open to collaborating on this.

Hey, your help was tremendous! It was very well done and you already have a good grasp of the Sphinx fundamentals; the only changes were tweaks specific to the syntax and formatting conventions used on this repo, which is something I help even our most experienced team members with. We'd love to work with you on any future contributions you'd like to make; feel free to open further issues or message us on Gitter if there's something else you'd like to work on (or would like some ideas/tips). Thanks again!