Development Environment Setup

Set up your local development environment to contribute to GitHub Desktop

Prerequisites

macOS

You will need to install these tools on your machine:

• Node.js
• Yarn
• Python 3
• Xcode and Xcode Command Line Tools (Xcode → Preferences → Downloads)

Windows

You will need to install these tools on your machine:

• Node.js
• Yarn
• Python 3
• Visual C++ Build Tools

Linux

You will need to install these tools on your machine:

• Node.js
• Yarn
• Python 3
• Electron dependencies

Installing Dependencies

macOS

1. Install Node.js

   Check if you have the right version of Node.js installed:

   node -v
   

   If you see an error, download Node from the Node.js website and install the package.

   Verify your installed version matches our .node-version file. Usually the same major version is enough.

   Using different Node.js versions across projects

   We support these Node version managers: nvm and asdf-nodejs.

   Using nvm:

   1. Install nvm using the instructions here
   2. Within the Desktop source directory, install the required version:
      nvm install
      
   3. Ensure you are running the right version:
      nvm use
      
   4. Verify by running node -v again

   Using asdf-nodejs:

   Check out the instructions here and here for installation details.

2. Install Yarn

   Follow this guide to install a system-level yarn.

   GitHub Desktop uses a local version of yarn, but it needs a version on your PATH to bootstrap itself. Yarn uses lock files to pin dependencies and prevent version mismatches between machines.

3. Verify Python 3

   macOS comes with Python pre-installed. Verify you have the right version:

   python3 --version
   

   You should see Python 3.9.x or similar.

   Using different Python versions across projects

   We recommend pyenv for managing Python versions.

   1. Install pyenv according to the instructions
   2. Within the Desktop source directory, install the required version:
      pyenv install
      
   3. Verify by running python3 --version again
4. Install Xcode Command Line Tools

   Run this command to install the Xcode command line tools:

   xcode-select --install
   

   If you already have them installed, it will notify you.

Windows

1. Install Node.js

   Check if you have the right version of Node.js installed:

   node -v
   

   If you see an error, download Node from the Node.js website and install the package.

   Make sure you allow the Node.js installer to add node to the PATH.

   Verify your installed version matches our .node-version file.

   Using different Node.js versions across projects

   We support nvm on Windows.

   1. Install nvm using the instructions here
   2. Within the Desktop source directory:
      nvm install
      
   3. Ensure you are running the right version:
      nvm use
      
   4. Verify by running node -v again
2. Install Yarn

   Follow this guide to install a system-level yarn.

   GitHub Desktop uses a local version of yarn, but it needs a version on your PATH to bootstrap itself.

3. Install Python 3

   Check your Python version:

   python --version
   

   You should see Python 3.9.x. If not, install Python 3.9 from the Python website.

   Important installation notes:

   • Let Python install into the default suggested path (c:\Python39), otherwise you’ll have to configure node-gyp manually
   • If you need a different path, set the PYTHON environment variable:
     npm config set python "c:\path\to\python3\python.exe"
     
   • Ensure the Add python.exe to Path option is selected
4. Install Visual C++ Build Tools

   To build native Node modules, you need Visual C++. Choose one option:

   Visual Studio 2019

   If you have VS2019 installed:

   1. Run the Visual Studio Installer (Tools > Get Tools and Features…)

   2. Check that you have the Desktop development with C++ workload included

   3. Update NPM configuration:

      npm config set msvs_version 2019
      npm config set msbuild_path "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\[VERSION]\\MSBuild\\Current\\Bin\\MSBuild.exe"
      
      VERSION will be Community, Professional, or Enterprise depending on your install.

   Visual Studio 2017

   If you have VS2017 installed:

   1. Run the Visual Studio Installer (Tools > Get Tools and Features…)
   2. Check that you have the Desktop development with C++ workload included
   3. Update NPM configuration:
      npm config set msvs_version 2017
      

   Visual C++ Build Tools (Standalone)

   If you don’t have Visual Studio:

   1. Install the standalone Visual C++ Build Tools
   2. Update NPM configuration:
      npm config set msvs_version 2019
      

Troubleshooting: If your local copy gets “stuck”, try deleting the folder C:\Users\[Your_User]\AppData\Roaming\GitHub Desktop-dev.

Linux

1. Install Node.js

   Find your distribution on this list and follow the instructions to install the required version.

   Ensure that you also choose the option for building native Node modules, as those are used in some dependencies.

2. Install Yarn

   Follow this guide to install a system-level yarn for your distribution.

   GitHub Desktop uses a local version of yarn, but it needs a version on your PATH to bootstrap itself.

3. Install Python 3

   Refer to your distribution’s package manager to obtain the latest version of the Python 3 series.

4. Install Electron dependencies

   Install these additional dependencies required for building and running GitHub Desktop:

   • libsecret-1.so.0 for reading and writing credentials using keytar
   • libXss.so.1 - the library for the X11 screen saver extension
   • libgconf-2-4.so.4 - library for accessing GNOME configuration database

   Fedora 26+

   sudo dnf install -y libsecret-devel libXScrnSaver
   

Verify Installation

Verify you have these commands available in your shell and that the found versions look similar to the output below:

node -v
# v20.17.0

yarn -v
# 1.21.1

python --version
# Python 3.9.x

Building Desktop

1. Fork and clone the repository

   Create a fork of desktop/desktop and clone it to your local machine. Navigate into the repository directory.

2. Install dependencies

   Run yarn to get all required dependencies:

   yarn
   
3. Create a development build

   Build the application for development:

   yarn build:dev
   
4. Launch the application

   Start the application:

   yarn start
   

   Changes will be compiled in the background. Reload the app to see changes using Ctrl/Command+Alt+R.

Optional Tip: On macOS and Linux, you can use screen to avoid filling your terminal with logging output:

screen -S "desktop" yarn start  # -S sets the name of the session
# Your screen clears and shows logs. Press Ctrl+A then D to exit.
screen -R "desktop"  # to reopen the session

If you’ve made changes in the main-process folder, you need to run yarn build:dev to rebuild the package, and then yarn start for these changes to be reflected in the running app.

Running Tests

Run all unit tests

yarn test

For more information on test arguments, see Node CLI options.

Debugging

1. Launch the app

   Run yarn start to launch the app.

2. Open Developer Tools

   Under the View menu, select Toggle Developer Tools.

   Electron ships with Chrome Dev Tools to assist with debugging, profiling, and other measurement tools.

When running the app in development mode, React Dev Tools should automatically install itself on first start.

Additional Resources

• Working with packages
• GitHub Enterprise authentication from dev build
• Troubleshooting guide
• Tooling configuration - Configure your favorite editor to work with the GitHub Desktop repository

Next Steps

Once your environment is set up, check out:

• Help Wanted - Tasks marked as ideal for external contributors
• Notes for Contributors - Guidance for new contributors getting started