For latest official version:

$ pip install --user vcspull


$ pip install --user --upgrade vcspull

Developmental releases

New versions of vcspull are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like a1, b1, and rc1, respectively. 1.10.0b4 would mean the 4th beta release of 1.10.0 before general availability.

  • pip:

    $ pip install --user --upgrade --pre vcspull
  • pipx:

    $ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force

    Then use vcspull@next sync [config]....

via trunk (can break easily):

  • pip:

    $ pip install --user -e git+https://github.com/vcs-python/vcspull.git#egg=vcspull
  • pipx:

    $ pipx install --suffix=@master 'vcspull @ git+https://github.com/vcs-python/vcspull.git@master' --force


We will check out the source code of flask to ~/code/flask.

Prefer JSON? Create a ~/.vcspull.json file:

  "~/code/": {
    "flask": "git+https://github.com/mitsuhiko/flask.git"

YAML? Create a ~/.vcspull.yaml file:

  "flask": "git+https://github.com/mitsuhiko/flask.git"

The git+ in front of the repository URL. Mercurial repositories use hg+ and Subversion will use svn+. Repo type and address is specified in pip vcs url format.

Now run the command, to pull all the repositories in your .vcspull.yaml / .vcspull.json.

$ vcspull sync

Also, you can sync arbitrary projects, lets assume you have a mercurial repo but need a git dependency, in your project add .deps.yaml (can be any name):

  sdl2pp: "git+https://github.com/libSDL2pp/libSDL2pp.git"

Use -c to specify a config.

$ vcspull sync -c .deps.yaml

You can also use fnmatch to pull repositories from your config in various fashions, e.g.:

$ vcspull sync django
$ vcspull sync django\*
$ vcspull sync "django*"

Filter by VCS URL:

Any repo beginning with http, https or git will be look up repos by the vcs url.

Pull / update repositories you have with github in the repo url:

$ vcspull sync "git+https://github.com/yourusername/*"

Pull / update repositories you have with bitbucket in the repo url:

$ vcspull sync "git+https://*bitbucket*"

Filter by the path of the repo on your local machine:

Any repo beginning with /, ./, ~ or $HOME will scan for patterns of where the project is on your system:

Pull all repos inside of ~/study/python:

$ vcspull sync "$HOME/study/python"

Pull all the repos you have in directories in my config with “python”:

$ vcspull sync ~/*python*