如何让`pip install -U`命令对通过Git仓库安装的pip包生效？

Great question! I’ve dealt with this exact scenario when maintaining Python packages hosted on GitHub branches, so let’s break down the solutions step by step.

Why pip install -U foo Doesn’t Work Out of the Box #

When you install a package using pip install git+ssh://git@github.com/myuser/foo.git@my_branch, pip records the package’s source as that specific Git branch—but by default, pip install -U only checks PyPI for updates. It doesn’t automatically poll the Git repository for new commits on your branch, which is why you have to re-run the full Git install command to upgrade.

1. Make pip install -U foo Work With a Configuration #

There are two reliable ways to configure pip so it automatically checks your Git branch for updates:

Method 1: Use pip’s find-links Configuration #

You can tell pip to prioritize your Git branch when looking for updates to foo by adding it to pip’s global configuration.

• First, locate your pip config file:

  • Linux/macOS: ~/.config/pip/pip.conf (create the file/folders if they don’t exist)
  • Windows: %APPDATA%\pip\pip.ini (same—create if missing)

• Add this content to the file:

  [global]
  extra-index-url = https://pypi.org/simple/  # Keep PyPI as the default for other packages
  [install]
  find-links = git+ssh://git@github.com/myuser/foo.git@my_branch#egg=foo
  

  The #egg=foo part is critical—it tells pip that this Git URL corresponds to the package named foo.

• Save the config, then run pip install -U foo—pip will now automatically pull the latest code from your specified Git branch to upgrade.

Method 2: Use Dynamic Versioning (Highly Recommended) #

If your package uses a fixed version number (e.g., 1.0.0), pip might skip upgrading even if there’s new code on the branch, since it sees the same version number. Fix this with dynamic versioning tied to Git commits:

• Use setuptools_scm to auto-generate version numbers based on your Git history:
  1. Install it first: pip install setuptools_scm
  2. Add this to your package’s pyproject.toml:

     [build-system]
     requires = ["setuptools>=61.0", "setuptools_scm"]
     build-backend = "setuptools.build_meta"
     
     [tool.setuptools_scm]
     

  Now, every new commit on your branch will generate a unique version number (e.g., 1.0.0.dev123+abc123), so pip will detect the update and upgrade when you run pip install -U foo.

2. Can You Add a GitHub Repository as an Extra Package Source? #

Strictly speaking, GitHub repos aren’t standard PyPI-compatible package indexes (which follow PEP 503). But you can achieve a similar effect:

• find-links as a per-package source: The method above using find-links effectively turns your Git branch into a dedicated source for foo, while keeping PyPI as the default for all other packages. This is the simplest approach for single packages.
• Self-hosted PyPI index: If you have multiple GitHub-hosted packages, you can set up a lightweight PyPI index (using tools like devpi or pypiserver), upload your packages to it, then add the index URL to pip’s extra-index-url config. This is overkill for one package, but useful for larger projects.

Quick Notes #

• Ensure your SSH key has access to the GitHub repo—otherwise, pip will fail to pull updates.
• If you switch branches, remember to update the Git URL in your pip config.
• pip install -U foo will only upgrade if the version number on the branch is newer than your local install—hence why dynamic versioning is so helpful.

内容的提问来源于stack exchange，提问作者Wang