Development Environment Setup

Prerequisites

macOS
Windows
Linux

You will need to install these tools on your machine:

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

Installing Dependencies

macOS
Windows
Linux

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:

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

Using asdf-nodejs:Check out the instructions here and here for installation details.

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.

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.

Install pyenv according to the instructions
Within the Desktop source directory, install the required version:
```
pyenv install
```
Verify by running python3 --version again

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.

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.

Install nvm using the instructions here
Within the Desktop source directory:
```
nvm install
```
Ensure you are running the right version:
```
nvm use
```
Verify by running node -v again

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.

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

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:

Run the Visual Studio Installer (Tools > Get Tools and Features…)
Check that you have the Desktop development with C++ workload included

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:

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

Visual C++ Build Tools (Standalone)

If you don’t have Visual Studio:

Install the standalone Visual C++ Build Tools
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.

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.

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.

Install Python 3

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

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

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

Fork and clone the repository

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

Install dependencies

Run yarn to get all required dependencies:

yarn

Create a development build

Build the application for development:

yarn build:dev

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

yarn test

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

Debugging

Launch the app

Run yarn start to launch the app.

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

Getting Started

Development

Architecture

Technical Guides

Project

Development Environment Setup

Prerequisites

Installing Dependencies

Verify Installation

Building Desktop

Running Tests

Debugging

Additional Resources

Next Steps

Build docs developers (and LLMs) love

Getting Started

Development

Architecture

Technical Guides

Project

​Prerequisites

​Installing Dependencies

​Verify Installation

​Building Desktop

​Running Tests

​Debugging

​Additional Resources

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Installing Dependencies

Verify Installation

Building Desktop

Running Tests

Debugging

Additional Resources

Next Steps