Explain Codes LogoExplain Codes Logo

How to state in requirements.txt a direct github source

python
pip-installation
requirements-file
package-management
Alex KataevbyAlex Kataev·Oct 23, 2024
TLDR

To incorporate a package directly from a GitHub repository in your requirements.txt file, here's the format to use:

git+https://github.com/USERNAME/REPO.git@BRANCH#egg=PACKAGE

Substitute USERNAME, REPO, BRANCH, and PACKAGE with the corresponding repository owner, repository name, branch/commit/tag, and intended package name. This elucidates pip on the need to clone the repository and install the mentioned package version. Crucially, ensure the presence of setup.py in the repository to define the package information.

If you fancy an editable install, engage the -e flag. However, ensure it's eliminated for production environments to maintain a particular version.

When a specific subdirectory within a repository houses the setup.py, specify it like so:

git+https://github.com/USERNAME/REPO.git@BRANCH#egg=PACKAGE&subdirectory=SUBDIRECTORY

For pip to detect new versions, updating the setup.py version is crucial.

For accessing private repositories, adopt token authentication for maximum security. Favor git+https over the less secure git+git.

Practical use cases and common pitfalls

Dealing with submodules and nested packages

If the package you fancy is buried as a submodule in a GitHub repo, it's still possible to get to it. Just specify the package directory after the #egg=PACKAGE part like this:

git+https://github.com/USERNAME/REPO.git@BRANCH#egg=PACKAGE&subdirectory=PATH/TO/SUBMODULE

Handling updates like a boss

To maintain synchrony with the latest commits from a branch, simply do away with the commit or tag. For reproducibility (not that we're in a lab, but why not?), opt for a specific commit:

git+https://github.com/USERNAME/REPO.git@COMMIT_HASH#egg=PACKAGE

Pro Tip (from a pro ogre), always test your installation every time you readjust:

pip install -r requirements.txt

Detect any hitches by checking the pip upgrade status and the compatibility of the package with your environment.

Advanced tips and tricks: Your guide to being a neighbors' envy

Keeping requirements up-to-date

After carefully installation, ensure the freshness of your project by creating a new requirements file:

# After all, freshness is our motto! pip freeze > requirements.txt

Protocol savvy: Not just drink protocol

Exercise preference for git+https owing to security – avoid git+git. Be a good scout and always validate your requirements file for accuracy and dodging camp time spooks.

Post-installation validation: Because who knows what gremlins lurk

Ensure everything works like clockwork post setup. Reinstall from the requirements like a clean slate to validate:

pip uninstall -y -r requirements.txt && pip install -r requirements.txt

Preparing for a glorious distribution

Planning to distribute your package? Aim to publish on PyPI. It not only makes your package more visibly appealing but also easier to manage dependencies.