Every so often, someone asks about whether you can develop for Open edX on Tutor using Windows. I’ve been trying out this setup for the past week now and found it to be a pretty nice experience. Ed suggested that I should write about my experiences while it’s still fresh in my mind, so I put this here in the hopes that someone might find it useful. Please keep in mind that I’m relatively new to using Windows for development, so I can’t say authoritatively that this is the Right Way to do this–it’s just what’s worked for me so far.
Background: I am running Windows 11 and using VS Code as my code editor. I do platform development, so I run tutor main, and use the latest versions of repos like edx-platform and openedx-learning during development.
The TLDR is that everything works fine as long as you leverage WSL as much as possible. The main source of confusion for me was that there are three environments at work–native Windows, WSL, and the Docker containers; and wasn’t always clear which one to use in a given situation.
Step 1: Install Windows Subsystem for Linux (WSL)
This is very straightforward and Microsoft has docs:
Step 2: Go to the Microsoft App Store and install “Ubuntu 24.04.1 LTS”
You can install any Linux distro that you’re comfortable with here. I just picked Ubuntu because I’m more familiar with it. This distro is the environment where you’ll eventually run tutor and git, but don’t do anything more than the bare installation yet.
(Note: It is possible to get things running by installing Tutor directly in Windows rather than using WSL, but it is absolutely not worth it. Even after you jump through all the hoops to make symlinks work properly, you’ll be stuck in a situation where the file performance is painfully slow. I made this mistake the first time).
Step 3: Install Docker Desktop for Windows
Install Docker Desktop for Windows. It has support for WSL integration, which you will definitely want to use. This integration makes it so that invoking docker commands from within your WSL Ubuntu distro will call out to the docker daemon that you installed in Windows.
Some settings you’ll want to check:
- General
Use the WSL 2 based engine
- Add the *.docker.internal names to the host’s /etc/hosts file (Requires password)
- Resources → WSL Integration
- Enable integration with my default WSL distro
- Make sure Ubuntu-24.04 (or whatever distro you installed in Step 2) is also enabled, if it’s not your default distro.
Once all this is done, you’ll be able to monitor all your containers in Docker Desktop on the Windows side, but still control everything from within your WSL distro.
Step 4: Set up your Linux distro environment
If you open Windows Terminal, you should have an option to open a shell to your WSL distro. Do so, install git (if it doesn’t already have it), pick whichever Python virtual environment solution you’ve found to be the least frustrating (I used uv), and install Tutor main per the docs.
Then run through all the normal steps for working on edx-platform as a developer. Just remember that you should be doing all these steps from inside your WSL distro terminal.
Step 5: Configure VS Code for editing
When you edit your files, you’ll want to connect VS Code directly to the Docker container and access the files that way, rather than doing so via the Windows fileshare of your WSL distro (again, because of terrible performance). To do this, install the “Dev Containers” plugin by Microsoft, which should in turn install a bunch of “Remote -” plugins and the “WSL” plugin. Also install Microsoft’s Python plugin and the Docker plugin.
Once all the plugins are installed, you should have a “Remote Explorer” button along the left side of your VS Code window. Select it, and then select the running container you want to access. For me this was tutor_main_dev tutor_main_dev-cms-1. Once you’ve connected, go to the “File” menu, select “Open Folder” and then navigate to /openedx/edx-platform. I currently also have another VS Code window open with the openedx-learning repo, located at /mnt/openedx-learning.
You should also definitely configure the Python plugin to point to the container’s Python environment at /openedx/venv.
Once you’re connected, you can also use VS Code’s built-in terminal to automatically open a shell into the container to run things like pytest and various management commands.
The major drawback with this approach is that if the runserver command dies altogether, then the entire container dies as well, and VS Code will disconnect entirely. This can currently happen if you make any change to your Python code that prevents Django from starting up correctly, including things like syntax errors. I’ve opened a PR to fix that, which should hopefully merge next week. Once it merges, the runserver command should stay up and running, even if there are Python errors during startup.
You can also load files into VS Code using the WSL plugin’s connection. In fact, if you have the WSL plugin installed and try to open a folder in your WSL distro via the folder in Windows file explorer, VS Code will warn you about it and ask if you want to re-open it through it’s WSL access mode. This is how you’ll edit tutor code itself, if you need to make changes on it.
Summary and Next Steps
In summary:
- Windows = Docker Desktop status viewing, launching VS Code, using the web browser
- WSL distro terminal = Where you run tutor commands and git checkouts/push/pull.
- Actual file editing happens using the container’s filesystem, accessed via the “Dev Containers” VS Code plugin. This lets you easily point to the container’s Python environment and get proper code introspection.
- My personal preference is to use VS Code’s terminal for all commands that have to run in the container, like management commands and pytest. Once you’re connected to the container for editing, the built-in terminal will automatically open up in the container.
I hope that was useful. I haven’t figured out connecting the debugger in this arrangement yet, though I do intend to look into it later. Comments and questions are welcome, though I may not have great answers for them. Thank you.