Introduction

pip can install directly from a GitHub repository, but it only works cleanly when a few pieces are in place: Git must be available on the machine, the repository must contain an installable Python project, and the URL syntax must match the repository access method. If any one of those is wrong, the install usually fails with an error that looks unrelated until you know what pip is trying to do behind the scenes.

The Basic GitHub Install Syntax

For a public repository, the most common form is a VCS URL using git+https.

pip install git+https://github.com/pallets/click.git

That tells pip to clone the Git repository and then install the Python package from the checked-out source.

If you need a specific branch, tag, or commit, append @ followed by the ref.

pip install git+https://github.com/pallets/[email protected]
pip install git+https://github.com/pallets/click.git@main

That is useful when you need a bug fix that is not yet on PyPI or when you want a reproducible install from a known revision.

Make Sure The Repository Is Installable

pip is not just downloading files from GitHub. It is expecting a Python project it can build and install.

At minimum, the repository should contain packaging metadata such as:

• 'pyproject.toml'
• or legacy setup.py
• optionally setup.cfg

A minimal modern pyproject.toml might look like this:

1[build-system]
2requires = ["setuptools>=61", "wheel"]
3build-backend = "setuptools.build_meta"
4
5[project]
6name = "example-package"
7version = "0.1.0"

If the repository is only source code with no Python packaging metadata, pip install from GitHub will not know how to build it.

Private Repositories And Authentication

For private repositories, HTTPS often requires credentials such as a GitHub token, while SSH requires the machine to have a configured key.

SSH form:

pip install git+ssh://[email protected]/your-org/private-repo.git

If you use SSH, test the connection separately first:

ssh -T [email protected]

For CI environments, it is usually safer to inject credentials through environment configuration than to hard-code them into the install command.

requirements.txt Support

The same GitHub install syntax works inside requirements.txt, which is often the cleanest place to keep it.

git+https://github.com/pallets/[email protected]

You can then install everything normally:

pip install -r requirements.txt

If the repository name and importable package name differ or you are working with older tooling, you may still see legacy #egg= syntax. Modern pip handles many cases without it, but some older setups still use it.

Repositories With A Package In A Subdirectory

Some monorepos keep the Python package in a subdirectory instead of the repository root. In that case, tell pip where the package lives.

pip install "git+https://github.com/example/monorepo.git@main#subdirectory=python-lib"

Without the subdirectory fragment, pip will look in the repository root and fail if the packaging files live elsewhere.

Common Pitfalls

The most common mistake is forgetting that Git itself must be installed and available on PATH. pip delegates the clone step to Git.

Another issue is trying to install from a repository that has no pyproject.toml or setup.py. A GitHub URL alone does not make the repository installable.

Authentication is another source of failures. Public repository commands may work locally but fail in CI when a private dependency is added and no credentials are configured.

Finally, be careful with reproducibility. Installing from a moving branch such as main can make builds drift unexpectedly. Tags or commit hashes are safer when stability matters.

Summary

• Use pip install git+https://github.com/user/repo.git for public GitHub installs.
• Make sure the repository is a real Python package with packaging metadata.
• Use SSH or tokens for private repositories, and test access outside pip first.
• Use @tag, @branch, or @commit for predictable installs.
• Add #subdirectory=... when the Python package is not at the repository root.