How to install and run Python code from GitHub

GitHubꜛ is widely used to share Python code, ranging from small collections of scripts to fully installable Python packages, often made accessible via conda or pip. However, there are also many repositories that are not (yet) available via conda or pip, but that you might want to use for your project. Depending on how a repository is structured, there are several ways to download, install, or run its code locally.

In this post, we go through six practical options:

1. Download the repository as a ZIP file and run the included Python scripts
2. Clone the repository using GitHub Desktop
3. Clone the repository using VS Code and Git
4. Clone the repository using the git command line tool
5. Install an installable Python package directly from GitHub with pip
6. Clone the repository using the GitHub CLI

In this post we briefly go through these options, which we apply to this test repositoryꜛ. This repository contains Python scripts that can be downloaded, cloned, and executed locally. The same principles apply to many other GitHub repositories, although the exact installation steps always depend on the repository structure and on the instructions provided by its authors.

Git? GitHub? What's the difference?

Before we start, let’s first briefly clarify the difference between Git and GitHub, as these terms are often used interchangeably, but they refer to different things.

Git is a version control system. It records changes in files over time, so that we can inspect previous versions, compare modifications, restore older states, and work on code in a structured way. In Python projects, Git is commonly used to manage scripts, notebooks, configuration files, documentation, and package source code.

GitHub is an online platform for hosting Git repositories. A repository is a project folder managed by Git. GitHub makes such repositories accessible through the web, allows developers to share code publicly or privately, and provides tools for collaboration, issue tracking, documentation, releases, and contributions through pull requests. There are also alternatives to GitHub, such as GitLab, Bitbucket, or Codeberg, which offer similar functionalities.

In short: Git is the version control tool. It can be installed locally on your computer and used through the command line or through graphical user interfaces. GitHub is a web platform that hosts Git repositories and adds collaboration features around them. You can use Git without GitHub, but you cannot use GitHub without Git.

Download the repository as a ZIP file and run the included Python scripts

The simplest option is to download a repository as a ZIP file. This does not require git, GitHub Desktop, or a GitHub account. It is therefore well suited for beginners or for cases where we only want to try out a repository once. However, this method downloads only a snapshot of the repository. The downloaded folder is not connected to GitHub. If the repository is updated later, we have to download a new ZIP file manually.

To download and run the repository as a ZIP file, follow these steps:

1. On the repository’s main website, click on the green Code button and choose Download ZIP:
2. Extract the Zip file and move the unpacked folder to the desired location on your hard drive.
3. Follow the installation instructions provided on the repository’s README file or documentation website. This usually includes opening a terminal, activating the desired Python environment, and changing into the extracted folder. For the example repository, we are advised to create a conda environment and install the requirements from the “requirements.txt” file:
   
   
   So:

     conda create -n Tkinter_tests -y python=3.9 pip
     conda activate Tkinter_tests
     pip install -r requirements.txt
   

4. After the dependencies have been installed, we can run a script from the repository. For our example:
   

     python calculator.py
   

   

This approach is sufficient if we only want to execute existing scripts. It is less suitable if we want to keep the repository synchronized with future updates.

Clone the repository using GitHub Desktop

Instead of downloading a ZIP snapshot, we can clone the repository to our hard drive. Cloning creates a local copy that remains connected to the original repository on GitHub. This makes it possible to fetch or pull later updates.

One convenient way to clone repositories is the GitHub Desktop appꜛ, which comes along with a GUI and makes the repository management quite handy and easy to use, especially if you do not want to manage repositories exclusively through the command line.

To clone the example repository with GitHub Desktop, follow these steps:

1. In the GitHub Desktop app, click on the Add button and choose Clone Repository...
2. In the dialog prompt:
   1. Enter the corresponding repository URL or <USERNAME/REPOSITORY>. For our example repository from above, simply enter:

        FabrizioMusacchio/Tkinter_GUI_examples
      

   2. Then choose the local path of the folder, in which you’d like to clone the repository. This can be, e.g., the folder of the project, for which you’d like to use the scripts in the repository. The repository will be cloned to a new folder inside that local path:
3. Follow steps 3 and 4 from option 1.

Whenever the original repository is updated by the repository contributors, the GitHub Desktop app detects these updates and offers the option to Pull origin, which will synchronize your local version with the repository:

Note: A cloned repository is still a Git repository. If we modify files inside the cloned folder, GitHub Desktop will show these files as local changes – to the local repository. These changes are not uploaded automatically to GitHub. And: They only become part of the local repository when we commit them, and they are only uploaded to GitHub when we push them:

In repositories where we do not have write access, we usually cannot push directly to the original repository. Contributions are typically made by creating a fork and opening a pull request.

Tip: If you only want to use the code, it is best not to modify the cloned repository directly. Instead, keep the scripts, data, and outputs outside the cloned folder. This way, you don’t have to worry about remote modifications.

Clone the repository using VS Code and Git

Another convenient option is to clone a GitHub repository directly from Visual Studio Codeꜛ (or short: VS Code). This is especially useful if you want to or already use VS Code as your main Python editor, because the repository can be cloned, opened, edited, and run from the same application.

In contrast to GitHub Desktop, VS Code does not include Git as a fully bundled replacement for a local Git installation. To use Git features, you have to install itꜛ on your operating system first.

To clone a repository with VS Code, follow these steps:

1. Open VS Code.
2. Open the Command Palette with Ctrl+Shift+P on Windows and Linux, or Cmd+Shift+P on macOS.
3. Search for Git: Clone and select it. Alternative, you can also click on “Clone Git Repository…” in the start window of VS Code.
4. Paste the repository URL.
   For the example repository, use this URL:
   

   https://github.com/FabrizioMusacchio/Tkinter_GUI_examples.git
   

5. Choose the local folder into which the repository should be cloned.

After cloning, VS Code asks you whether the cloned repository should be opened. Choose Open, which opens the cloned repository as a project folder.

The Source Control view shows the Git status of the repository (click on the Source Control icon in the left/right sidebar). If files are modified, they appear as local changes. From there, changes can be staged, committed, synchronized, or discarded (we explain these options in the next section).

To run Python code from the cloned repository, open a terminal inside VS Code: Terminal->New Terminal and follow the installation instructions provided in the repository’s README file or documentation website, as described in option 1. For the example repository:

conda create -n Tkinter_tests -y python=3.9 pip
conda activate Tkinter_tests
pip install -r requirements.txt

Troubleshooting on Windows

On Windows the activation command may depend on the shell and on how conda was initialized. A dedicated general troubleshooting guide for running conda on Windows machines is provided in this blog post.

Using VS Code is a good option if we want to inspect, edit, and run the code in one place. It is also useful for Python projects because VS Code can select the Python interpreter of the active environment, run scripts, execute notebooks, and integrate Git version control in the same interface.

However, the same caution applies as with every cloned repository: If you only want to use the code, you should avoid modifying files inside the cloned repository unless you intentionally want to track these changes with Git. Your own scripts, notebooks, data, and output files are often better kept in a separate project folder.

Clone the repository using the git command line tool

If you have installed Gitꜛ on your OS, you can carry out the same steps with the command lineꜛ as with the GitHub Desktop app:

1. Copy the URL of the repository: The URL for our example repository is:

     https://github.com/FabrizioMusacchio/Tkinter_GUI_examples.git
   

2. Open a terminal and change the current working directory (cd) to the location where you want the cloned directory.
3. Then type:
   
   

     git clone https://github.com/FabrizioMusacchio/Tkinter_GUI_examples.git
   

   This creates a new folder called Tkinter_GUI_examples. We can enter this folder with:
   
   

     cd Tkinter_GUI_examples
   

4. Again, then follow steps 3 and 4 from option 1.

Using the command line gives us more control and flexibility. For example, we can check the current status of the repository by typing:

git status

The status command tells us whether there are local modifications, whether files are untracked, and whether the current branch is synchronized with the remote repository.

To download information about updates from GitHub without changing the local working files, use:

git fetch

fetchꜛ downloads new information from the remote repository, but it does not modify the current working files, i.e., it only updates the local repository with the new commits and branches from GitHub, but it does not merge these changes with the local files. This means that after fetching, we can inspect the new commits and branches, but our local files remain unchanged. If we want to update our local files with the new commits from GitHub, we have to merge them:

git merge

The pullꜛ command combines both, fetching and merging, in one command:

git pull

The pull command only merges committed local changes with the remote repository.

Since gitꜛ is an open-source version control system, it is meant to store and manage different versions of our code stored on our local hard drive or in a remote repository (like GitHub). To create such versions with git, we have to commitꜛ them (i.e., the changes in our files) via

git commit -m "some explanatory commit comment"

However, before committing changes, the modified files usually have to be staged using the add command:

git add filename.py

or, to stage all current changes:

git add .

Remeber, with

git status

we can get a quick summary of the current status of our repository. And with the logꜛ command,

git log

we can browse and inspect the history of the files in the repository.

In summary
For normal users who only want to download and run code, the most important git commands are usually:

git clone
git status
git fetch
git pull

The commands add, commit, and push become important when we actively develop code or contribute changes back to a repository.

Install an installable Python package directly from GitHub with pip

Some GitHub repositories are structured as installable Python packages. Such repositories usually contain a file such as:

• pyproject.toml
• setup.py
• setup.cfg

If this is the case, the package can often be installed directly from GitHub with pip, even if it is not available on PyPI or conda-forge.

The general syntax is:

pip install git+https://github.com/USERNAME/REPOSITORY.git

For example:

pip install git+https://github.com/someuser/somepackage.git

This installs the package into the currently active Python environment. Therefore, we should first create/activate the environment in which the package should be installed:

conda create -n github_package_test -y python=3.11 pip
conda activate github_package_test
pip install git+https://github.com/USERNAME/REPOSITORY.git

We can also install a specific branch (a branch is a parallel version of the repository, which can contain different code than the main branch),

pip install git+https://github.com/USERNAME/REPOSITORY.git@branch-name

a specific release tag (a release tag is a specific version of the repository, which is usually more stable than the main branch):

pip install git+https://github.com/USERNAME/REPOSITORY.git@v1.2.0

or a specific commit (i.e., a specific change in the repository, which can be identified by its unique hash):

pip install git+https://github.com/USERNAME/REPOSITORY.git@commit_hash

This is often the cleanest method if the repository is a proper Python package. After the installation, the package can usually be imported from anywhere in the active Python environment:

import package_name

However, this method only works if the GitHub repository is structured as an installable Python package. If the repository only contains loose scripts, notebooks, images, example files, or data, then downloading or cloning the repository is usually the better option.

If the repository contains a requirements.txt file, this file can install dependencies, but it does not necessarily mean that the repository itself is an installable package. In such cases, we may still have to clone or download the repository and run the scripts manually.

Clone the repository using the GitHub CLI

A further option is the GitHub CLIꜛ. This is a command line tool provided by GitHub.

After installing and configuring the GitHub CLI, a repository can be cloned with:

gh repo clone USERNAME/REPOSITORY

For the example repository:

gh repo clone FabrizioMusacchio/Tkinter_GUI_examples

This is similar to git clone, but more closely integrated with GitHub. It can also simplify workflows involving authentication, private repositories, forks, issues, and pull requests.

For beginners who only want to download and run Python code, GitHub Desktop or the normal git clone command are usually sufficient. The GitHub CLI becomes more useful when we interact with GitHub frequently from the command line.

Which method should you use?

The best method depends on what you want to do with the repository.

If you only want to try a repository once, downloading it as a ZIP file is usually sufficient. It is simple, does not require git, and avoids unnecessary complexity.

If you want to keep the local copy synchronized with future updates, cloning the repository is better. GitHub Desktop is convenient for users who prefer a graphical interface and do not necessarily want to use git directly from the terminal. VS Code with Git is often the most convenient option if you already use VS Code for Python development, because cloning, editing, running scripts, selecting environments, and basic Git version control can be handled in one place. The git clone command is better for users who are comfortable with the terminal and want direct control over the Git workflow.

If the repository is an installable Python package, installing it directly with pip from GitHub is often the most convenient option. This makes the package available in the active Python environment, just like a package installed from PyPI.

If you work with GitHub frequently from the command line, the GitHub CLI can also be useful.

In practice, the most common workflows are:

• Download a local copy with git:

  git clone https://github.com/USERNAME/REPOSITORY.git
  

• or clone the repository directly from VS Code via the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on macOS) and type:

    Git: Clone
  

• Install dependencies from a requirements file:

  pip install -r requirements.txt
  

• Run a Python script:

  python script_name.py
  

• Alternatively, install an installable Python package directly from GitHub (if the repository is structured as a package):

  pip install git+https://github.com/USERNAME/REPOSITORY.git
  

The repository documentation should always be checked first. Good repositories usually contain a README.md file with installation instructions, dependency information, and examples. If such instructions exist, they should be followed before trying a generic installation method.