Fix typos and update Apple Silicon instructions in Mac install docs (#506)

rohanmalhotracodes · web-flow · commit bc3114320b8e · 2026-02-25T09:35:18.000-05:00
* Fix typos and update Apple Silicon instructions in Mac install docs Updates Apple Silicon wording and fixes minor typos per issues #502, #503, #505. * Update architecture switching instructions for Oppia Restored wording that switching to Intel architecture is required for Oppia development on Apple Silicon Macs, to avoid ambiguity for first-time setup. * Fix capitalization and formatting in installation guide
diff --git a/Installing-Oppia-(Mac-OS;-Python-3).md b/Installing-Oppia-(Mac-OS;-Python-3).md
@@ -1,6 +1,6 @@
 ## Table of Contents
 
-* [Macs with M1 chips](#macs-with-m1-chips)
+* [Macs with Apple Silicon](#macs-with-apple-silicon)
 * [Install prerequisites](#install-prerequisites)
 * [Clone Oppia](#clone-oppia)
 * [Setup a virtual environment](#setup-a-virtual-environment)
@@ -13,13 +13,13 @@
 
 **Note:** Be careful about trying to install Oppia if you have the Python [Anaconda platform](https://www.anaconda.com/) installed. We've received a bunch of reports that installation is tricky in that environment (there are lots of small things that get in the way), and that the solution is to use the standard python installation (via e.g. homebrew) instead.
 
-## Macs with M1 chips
+## Macs with Apple Silicon
 
-To check whether your Mac has an M1 chip, navigate to the Apple menu and select "About This Mac." In the window that opens, check for a "Chip" section. If it says "Apple M1" then you have an M1 chip. Otherwise, you should see an Intel processor listed in the "Processor" section. [This article](https://www.howtogeek.com/706226/how-to-check-if-your-mac-is-using-an-intel-or-apple-silicon-processor/) explains in more detail with screenshots if you have trouble.
+To check whether your Mac has an Apple Silicon chip (M1/M2/M3 and newer), navigate to the Apple menu and select "About This Mac." In the window that opens, check for a "Chip" section. If it says "Apple M1", "Apple M2", "Apple M3", etc., then you have an Apple Silicon Mac. Otherwise, you should see an Intel processor listed in the "Processor" section. [This article](https://www.howtogeek.com/706226/how-to-check-if-your-mac-is-using-an-intel-or-apple-silicon-processor/) explains in more detail with screenshots if you have trouble.
 
-If your Mac has an M1 chip, follow these instructions first:
+If your Mac has an Apple Silicon chip, follow these instructions first:
 
-1. If not yet done so, install Rosetta 2 with the following command:  `softwareupdate --install-rosetta`. Rosetta 2 translates Intel-based apps to run on Apple silicon Macs.
+1. If not yet done so, install Rosetta 2 with the following command:  `softwareupdate --install-rosetta`. Rosetta 2 translates Intel-based apps to run on Apple Silicon Macs.
 
    [Rosetta](https://support.apple.com/en-us/HT211861) is Apple's compatibility layer that lets you run apps written for Intel chips on Apple Silicon. You can install Rosetta 2 by running:
 
@@ -48,13 +48,13 @@ If your Mac has an M1 chip, follow these instructions first:
 
    The `arm64` indicates Apple Silicon, while the `i386` indicates that we are running under Rosetta.
 
-2. Next, we will create a Rosetta terminal that emulate the *Intel* architecture. To do so, open a new terminal and run the following command (change "bash" to "zsh" if you're using a zsh terminal):
+2. Next, we will create a Rosetta terminal that emulates the *Intel* architecture. To do so, open a new terminal and run the following command (change "bash" to "zsh" if you're using a zsh terminal):
 
     ```shell
     $ /usr/bin/arch -x86_64 $SHELL --login
     ```
 
-    This switches the architecture from Mac M1's *ARM* architecture to the emulated *Intel* architecture for the current session. To verify this, run `arch` in the terminal and you should see `i386` being printed. You will need to switch the architecture to Intel for all Oppia development.
+    This switches the architecture from Apple Silicon’s *ARM* architecture to the emulated *Intel* architecture for the current session. To verify this, run `arch` in the terminal and you should see `i386` being printed. You will need to switch the architecture to Intel for all Oppia development.
 
     If you use Homebrew to install any Python development dependencies for pyenv (discussed below), you will need to install and use Homebrew in this terminal as well. Note that while you can have a Homebrew installation for Apple Silicon and another for Intel architectures installed simultaneously, pyenv is not smart enough to pick the Intel dependencies if both are present, so we recommend using an Intel installation of Homebrew exclusively.
 
@@ -149,7 +149,7 @@ Oppia relies on a number of programs and third-party libraries. Many of these li
 
 ## Setup a virtual environment
 
-For your vitual environment, we recommend you use [pyenv](https://github.com/pyenv/pyenv). Here are some instructions for doing so, but you can use another virtual environment tool if you wish:
+For your virtual environment, we recommend you use [pyenv](https://github.com/pyenv/pyenv). Here are some instructions for doing so, but you can use another virtual environment tool if you wish:
 
 1. **Make sure you install the Python build dependencies for your operating system. These are specified [here](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). If you don't do this it might lead to problems further on.**
 
@@ -228,7 +228,7 @@ For your vitual environment, we recommend you use [pyenv](https://github.com/pye
    python -m scripts.start
    ```
 
-   The first time you run this script, it will take a while (about 5 - 10 minutes when we last tested it in Dec 2018, though this depends on your Internet connection). Subsequent runs should be much faster. The `start.py` script downloads and installs the required dependencies (such as Google App Engine) if they are not already present, and sets up a development server for you to play with. The development server logs are then output to this terminal, so you will not be able to enter further commands in it until you disconnect the server.
+   The first time you run this script, it will take a while (around 10 minutes when we last tested it, though this depends on your internet connection). Subsequent runs should be much faster. The `start.py` script downloads and installs the required dependencies (such as Google App Engine) if they are not already present, and sets up a development server for you to play with. The development server logs are then output to this terminal, so you will not be able to enter further commands in it until you disconnect the server.
 
    > [!CAUTION]
    > **Please don't use `sudo` while installing.** It's not required, and using it may cause problems later. If you face permissions issues, ensure that you have the necessary permissions for the directory in which you're trying to set up Oppia. If you run into any other installation problems, please read [[these notes|Issues-with-installation]]
diff --git a/Installing-Oppia-(Windows;-Python-3).md b/Installing-Oppia-(Windows;-Python-3).md
@@ -3,12 +3,12 @@
 * [Installing Oppia in Windows and WSL2](#installing-oppia-in-windows-and-wsl2)
   * [Step 1: Check if your Windows is up to date](#step-1-check-if-your-windows-is-up-to-date)
   * [Step 2: Install WSL2](#step-2-install-wsl2)
-  * [Step 3: Install the ubuntu app from the Microsoft Store](#step-3-install-the-ubuntu-app-from-the-microsoft-store)
+  * [Step 3: Install the Ubuntu app from the Microsoft Store](#step-3-install-the-ubuntu-app-from-the-microsoft-store)
   * [Step 4: Clone your fork and setup](#step-4-clone-your-fork-and-setup)
   * [Step 5: Download and install google-chrome (in the Ubuntu Environment)](#step-5-download-and-install-google-chrome-in-the-ubuntu-environment)
   * [Step 6: Add a lightweight desktop environment](#step-6-add-a-lightweight-desktop-environment)
     * [Edit desktop environment config](#edit-desktop-environment-config)
-  * [Step 7: Start the rdp server](#step-7-start-the-rdp-server)
+  * [Step 7: Start the RDP server](#step-7-start-the-rdp-server)
   * [Step 8: Connect to the server using the Windows RDP client](#step-8-connect-to-the-server-using-the-windows-rdp-client)
   * [Step 9: Run Oppia locally](#step-9-run-oppia-locally)
   * [How to run the E2E tests?](#how-to-run-the-e2e-tests)
@@ -35,7 +35,7 @@
 
 *For information on issues that may occasionally arise with the installation process, please see the [Troubleshooting](https://github.com/oppia/oppia/wiki/Troubleshooting) page.*
 
-There follow instructions for 3 different ways to install Oppia on Windows: using WSL2, using VirtualBox, and using WSL1. You only need to follow one of the four.
+The following are instructions for 3 different ways to install Oppia on Windows: using WSL2, using VirtualBox, and using WSL1. You only need to follow one of the three.
 **The first approach (Installing Oppia in Windows and WSL2) is recommended.**
 
 Note: If you already use VirtualBox, it will stop working after installing WSL2 because the hypervisor resource gets locked by WSL2, and can't be used by VirtualBox. WSL2 is much faster, but make sure to copy over all your data from the VM before proceeding with the installation of WSL2.
@@ -44,11 +44,11 @@ Note: If you already use VirtualBox, it will stop working after installing WSL2
 
 ## Step 1: Check if your Windows is up to date
 
-To do so press "windows-key + r" and type `winver`.
+To do so press "Windows-key + r" and type `winver`.
 
 ![Screenshot 2020-09-18 at 11 56 20 PM](https://user-images.githubusercontent.com/23002114/93634575-75bc9200-fa0e-11ea-8690-98afbda2a02e.png)
 
-This will open up a window. Note down your windows version number and build number.
+This will open up a window. Note down your Windows version number and build number.
 
 ![Screenshot 2020-09-18 at 11 56 54 PM](https://user-images.githubusercontent.com/23002114/93634585-79e8af80-fa0e-11ea-97f8-d60275130e01.png)
 
@@ -63,10 +63,10 @@ Make sure your version and build meet the following criteria:
 
 You can install WSL2 by following the steps [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10) until step 5.
 
-* The windows version number and build number will be useful in determining whether or not your system needs to be updated.
+* The Windows version number and build number will be useful in determining whether or not your system needs to be updated.
 
 
-## Step 3: Install the ubuntu app from the Microsoft Store
+## Step 3: Install the Ubuntu app from the Microsoft Store
 
 Install Ubuntu 18.04 LTS from the Microsoft Store.
 
@@ -77,7 +77,7 @@ Once it is installed, run the app from the startup menu. After initializing your
 |-|-|
 |![Screenshot 2020-09-18 at 11 57 22 PM](https://user-images.githubusercontent.com/23002114/93634596-7e14cd00-fa0e-11ea-8a07-0b4b65499225.png)|![Screenshot 2020-09-18 at 11 57 35 PM](https://user-images.githubusercontent.com/23002114/93634597-7fde9080-fa0e-11ea-8ba1-0c29be080fd7.png)|
 
-**Note: You can go for Ubuntu 20.04 or "Ubuntu" as well but it comes as a barebones config. It means that you will have to install all the libs yourself, i.e, gcc, make, etc to run oppia. If you are familiar with these processes then you can use these as well.**
+**Note: You can go for Ubuntu 20.04 or "Ubuntu" as well but it comes as a barebones config. It means that you will have to install all the libs yourself, i.e., gcc, make, etc. to run Oppia. If you are familiar with these processes then you can use these as well.**
 
 ## Step 4: Clone your fork and setup
 
@@ -87,7 +87,7 @@ If you are facing problems with pushing the code to your fork check this link: [
 
 ## Step 5: Download and install google-chrome (in the Ubuntu Environment)
 
-_Even if you have Chrome installed on you windows system, you still need to do this to run E2E tests and unit tests._
+_Even if you have Chrome installed on your Windows system, you still need to do this to run E2E tests and unit tests._
 
 Run the following commands to download latest chrome:
 
@@ -136,18 +136,18 @@ Add these lines:
 startxfce4
 ```
 
-Once inside Nano, you can use the arrow keys to move between lines. When you are done with your changes press: `ctrl+x` followedby `Y` followedby enter to save the file.
+Once inside Nano, you can use the arrow keys to move between lines. When you are done with your changes press: `ctrl+x` followed by `Y` followed by enter to save the file.
 You can read more about RDP, XFCE, XRDP in the [Appendix](#appendix).
 
-## Step 7: Start the rdp server
+## Step 7: Start the RDP server
 
 ```console
 sudo /etc/init.d/xrdp start
 ```
 
 ## Step 8: Connect to the server using the Windows RDP client
 
-The name of the app is "Remote Desktop Connection". It is already installed in the windows system by default. No need to use any third-party app.
+The name of the app is "Remote Desktop Connection". It is already installed in the Windows system by default. No need to use any third-party app.
 
 ![Screenshot 2020-09-19 at 12 33 03 AM](https://user-images.githubusercontent.com/23002114/93635466-f334d200-fa0f-11ea-99d3-da39d4deecd8.png)
 
@@ -168,13 +168,13 @@ Navigate to any browser and access Oppia at http://localhost:8181.
 
 ## How to run the E2E tests?
 
-Open the terminal (in the ubuntu-desktop env/ the RDP client) and run `google-chrome`. Then Open a new terminal tab and run your e2e tests 🙂. To check you can run `python -m scripts.run_e2e_tests --suite="users"`.
+Open the terminal (in the ubuntu-desktop env/ the RDP client) and run `google-chrome`. Then open a new terminal tab and run your e2e tests 🙂. To check you can run `python -m scripts.run_e2e_tests --suite="users"`.
 
 **Note: You only need to use the RDP client to run e2e tests. You don't have to start the X server for developing and pushing code.**
 
 ## Miscellaneous
 
-- The WSL environment does not support audio, but it can be enabled by installing the [PulseAudio](https://wiki.ubuntu.com/PulseAudio) server on Windows following [this guide](https://token2shell.com/howto/x410/enabling-sound-in-wsl-ubuntu-let-it-sing/). With the latest [wslu package](https://launchpad.net/ubuntu/+source/wslu) installed the starting Ubuntu app detects the running [PulseAudio](https://wiki.ubuntu.com/PulseAudio) server and enables audio.
+- The WSL environment does not support audio, but it can be enabled by installing the [PulseAudio](https://wiki.ubuntu.com/PulseAudio) server on Windows following [this guide](https://token2shell.com/howto/x410/enabling-sound-in-wsl-ubuntu-let-it-sing/). With the latest [wslu package](https://launchpad.net/ubuntu/+source/wslu) installed, the Ubuntu app on startup detects the [PulseAudio](https://wiki.ubuntu.com/PulseAudio) server and enables audio.
 - VSCode comes with an extension called remote-wsl, that makes it very easy to code when the code exists in your Ubuntu folder.
 - Per [this AskUbuntu question](https://askubuntu.com/questions/1115564/wsl-ubuntu-distro-how-to-solve-operation-not-permitted-on-cloning-repository), Git clone doesn’t work on mounted drives within WSL so be sure not to use it.
 - When in the Ubuntu file system, you can type `explorer.exe .`  (don't forget the extra dot at the end) to open that folder in your Windows file explorer.
@@ -195,7 +195,7 @@ Any VM manager is fine, but the instructions here are specific to VirtualBox.
 
 1. Install VirtualBox from [here](https://www.virtualbox.org/wiki/Downloads).
 2. Open VirtualBox and click New.
-3. Select Type as "Linux", Version "Ubuntu 64bit" and give some name for the VM.
+3. Select Type as "Linux", Version "Ubuntu 64-bit" and give some name for the VM.
 4. In the next page, select an appropriate amount of RAM for the VM (can be changed later). The whole dev environment is verified to work smoothly at 6 GB RAM. At least 4 GB is recommended.
 5. In the next page, select "Create a virtual hard disk now" and click Create.
 6. Select VDI as the file type.
@@ -204,10 +204,10 @@ Any VM manager is fine, but the instructions here are specific to VirtualBox.
 
 ## Install Ubuntu 18 ISO
 
-1. Download the Ubuntu 18.04 64bit ISO from [here](https://releases.ubuntu.com/18.04/).  Alternatively the version 22.04 can be downloaded from (https://releases.ubuntu.com/jammy/).
+1. Download the Ubuntu 18.04 64-bit ISO from [here](https://releases.ubuntu.com/18.04/).  Alternatively the version 22.04 can be downloaded from (https://releases.ubuntu.com/jammy/).
 2. Select the newly created VM in the virtual box and click Start.
 3. Here, a window pops up where you have to link the downloaded ISO file. Click the folder icon and select the ISO from your machine.
-4. Now, go through the normal Ubuntu installation steps, you can do the following the specific steps:
+4. Now, go through the normal Ubuntu installation steps, you can do the following specific steps:
  * Select "Minimal Installation", and check both checkboxes below it.
  * Select "Erase disk and install Ubuntu". Don't worry, no data in your host machine will be affected :).
 5. Once, Ubuntu is running and everything is done installing, exit from VM.
