Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# VCS Support

pip supports installing from various version control systems (VCS). This support requires a working executable to be available (for the version control system being used). It is used through URL prefixes:

- Git -- `git+`

- Mercurial -- `hg+`

- Subversion -- `svn+`

- Bazaar -- `bzr+`

## Supported VCS

### Git

The supported schemes are `git+file`, `git+https`, `git+ssh`, `git+http`, `git+git` and `git`. Here are some of the supported forms:

    MyProject @ git+ssh://git@git.example.com/MyProject
    MyProject @ git+file:///home/user/projects/MyProject
    MyProject @ git+https://git.example.com/MyProject

Warning

The use of `git`, `git+git`, and `git+http` schemes is discouraged. The former two use the Git Protocol, which lacks authentication, and HTTP is insecure due to lack of TLS based encryption.

It is also possible to specify a “git ref” such as branch name, a commit hash or a tag name:

    MyProject @ git+https://git.example.com/MyProject.git@master
    MyProject @ git+https://git.example.com/MyProject.git@v1.0
    MyProject @ git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709
    MyProject @ git+https://git.example.com/MyProject.git@refs/pull/123/head

When passing a commit hash, specifying a full hash is preferable to a partial hash because a full hash allows pip to operate more efficiently (e.g. by making fewer network calls).

### Mercurial

The supported schemes are `hg+file`, `hg+http`, `hg+https`, `hg+ssh` and `hg+static-http`. Here are some of the supported forms:

    MyProject @ hg+http://hg.myproject.org/MyProject
    MyProject @ hg+https://hg.myproject.org/MyProject
    MyProject @ hg+ssh://hg.myproject.org/MyProject
    MyProject @ hg+file:///home/user/projects/MyProject

It is also possible to specify a revision number, a revision hash, a tag name or a local branch name:

    MyProject @ hg+http://hg.example.com/MyProject@da39a3ee5e6b
    MyProject @ hg+http://hg.example.com/MyProject@2019
    MyProject @ hg+http://hg.example.com/MyProject@v1.0
    MyProject @ hg+http://hg.example.com/MyProject@special_feature

### Subversion

The supported schemes are `svn`, `svn+svn`, `svn+http`, `svn+https` and `svn+ssh`. Here are some of the supported forms:

    MyProject @ svn+https://svn.example.com/MyProject
    MyProject @ svn+ssh://svn.example.com/MyProject
    MyProject @ svn+ssh://user@svn.example.com/MyProject

You can also give specific revisions to an SVN URL, like so:

    -e svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject
    -e svn+http://svn.example.com/svn/MyProject/trunk@{20080101}#egg=MyProject

Note that you need to use Editable VCS installs for using specific revisions from Subversion.

### Bazaar

The supported schemes are `bzr+http`, `bzr+https`, `bzr+ssh`, `bzr+sftp`, `bzr+ftp` and `bzr+lp`. Here are the supported forms:

    MyProject @ bzr+http://bzr.example.com/MyProject/trunk
    MyProject @ bzr+sftp://user@example.com/MyProject/trunk
    MyProject @ bzr+ssh://user@example.com/MyProject/trunk
    MyProject @ bzr+ftp://user@example.com/MyProject/trunk
    MyProject @ bzr+lp:MyProject

Tags or revisions can be installed like so:

    MyProject @ bzr+https://bzr.example.com/MyProject/trunk@2019
    MyProject @ bzr+http://bzr.example.com/MyProject/trunk@v1.0

## Editable VCS installs

VCS projects can be installed in editable mode (using the --editable option) or not.

- The default clone location (for editable installs) is:

  - `<venv path>/src/SomeProject` in virtual environments

  - `<cwd>/src/SomeProject` for global Python installs

  The --src option can be used to modify this location.

- For non-editable installs, the project is built locally in a temp dir and then installed normally.

Note that if a satisfactory version of the package is already installed, the VCS source will not overwrite it without an `--upgrade` flag. Further, pip looks at the package version, at the target revision to determine what action to take on the VCS requirement (not the commit itself).

## URL fragments

pip looks at the `subdirectory` fragments of VCS URLs for specifying the path to the Python package, when it is not in the root of the VCS directory. eg: `pkg_dir`.

pip also looks at the `egg` fragment specifying the “project name”. In practice the `egg` fragment is only required to help pip determine the VCS clone location in editable mode. In all other circumstances, the `egg` fragment is not necessary and its use is discouraged.

The `egg` fragment should be a bare project name. Anything else is not guaranteed to work.

Example

If your repository layout is:

    pkg_dir
    ├── setup.py  # setup.py for package "pkg"
    └── some_module.py
    other_dir
    └── some_file
    some_other_file

Then, to install from this repository, the syntax would be:

Linux

    $ python -m pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir"

MacOS

    $ python -m pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir"

Windows

    C:> py -m pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir"

or:

Linux

    $ python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"

MacOS

    $ python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"

Windows

    C:> py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"