Introduction

pip can install a Python package from a Git repository even when the package lives in a nested folder instead of the repository root. The trick is to point pip at the repository revision and also tell it which subdirectory contains the Python package metadata.

This is common in monorepos where one repository contains several packages, tools, or non-Python code. As long as the subdirectory has a valid pyproject.toml or other supported build metadata, pip can install it directly.

The command looks a little unusual at first, but once the package root is identified correctly the installation flow is no different from any other pip install.

Use a VCS URL with a Subdirectory Fragment

The classic form looks like this:

pip install "git+https://github.com/example/monorepo.git@main#egg=my_package&subdirectory=python/sdk"

The important pieces are:

• the Git URL
• the branch, tag, or commit after @
• the package name after #egg=
• the nested package path after subdirectory=

If the subdirectory is wrong, pip may clone the repository successfully and then fail when it cannot find package metadata.

That specific failure mode is useful because it tells you Git access worked and the remaining bug is the package path, not repository access.

Prefer a Direct Reference When Supported

Modern pip also supports a more readable direct-reference form:

pip install "my_package @ git+https://github.com/example/[email protected]#subdirectory=python/sdk"

This is especially nice in requirements.txt because the dependency name appears first:

my_package @ git+https://github.com/example/[email protected]#subdirectory=python/sdk

That makes the file easier to scan and less tied to older #egg= conventions.

Pin a Revision for Reproducibility

Installing from @main is convenient during development, but it makes builds non-deterministic. For repeatable environments, use a tag or commit hash:

pip install "my_package @ git+https://github.com/example/monorepo.git@3f6b2f8#subdirectory=python/sdk"

That way the same install command always resolves to the same code.

This is especially important in CI and deployment pipelines, where a moving branch can make "the same build" produce different environments on different days.

Make Sure the Subdirectory Is a Real Package Root

The target folder must contain a valid Python package build configuration. Typical cases include:

• 'pyproject.toml'
• 'setup.py'
• 'setup.cfg with the appropriate build metadata'

For example:

1repo/
2  python/
3    sdk/
4      pyproject.toml
5      src/
6        my_package/

In that layout, the correct value is subdirectory=python/sdk, not just subdirectory=python.

Private Repositories Need Authentication

For private repositories, use an authentication method that fits the environment. SSH is a common choice when deploy keys or user keys already exist:

pip install "my_package @ git+ssh://[email protected]/example/private-repo.git@main#subdirectory=python/sdk"

Avoid hard-coding secrets in requirements files. In CI, prefer short-lived tokens or managed SSH keys supplied by the platform.

Whichever authentication method you choose, test it with a plain git clone first if installation fails early. That separates Git access problems from pip packaging problems.

Common Pitfalls

• Pointing subdirectory at a parent folder that does not actually contain package metadata.
• Installing from a moving branch when the build should be reproducible.
• Forgetting that the nested package still needs a valid pyproject.toml or equivalent.
• Mixing authentication into URLs in a way that leaks secrets.
• Assuming pip will install everything in the repository instead of only the selected package.

Summary

• 'pip can install directly from a Git subdirectory.'
• Use either the classic VCS URL form or a direct-reference form with subdirectory=.
• Point at the exact folder that contains the Python package metadata.
• Prefer tags or commits for reproducible installs.
• Use secure authentication methods for private repositories.