In some documents or blogs about development in open source projects, you can read stuff like 'upstream developer' or 'upstream fix'. What does that mean?

4 Answers 4


Consider the obvious analogy (from which the term flows - pun intended) ... water in a river flows 'downstream' and thus 'upstream' is the source from which the water comes.

This analogy is deeply embedded in software development, so it's no mere coincidence that we use terms like 'head', 'source', 'upstream', 'downstream' and even 'flow' extensively in the field.

In the context of a forked software project, the 'upstream' is the source from which a particular project was forked. This might not be the absolute origin.

If project A is forked to produce project B which is then forked to produce project C, then B is 'upstream' of C and A is upstream of B (and C).

Thus, an upstream developer is one who works on an upstream project. An upstream fix is one which exists in the upstream (parent) project.

When working with Git, especially in the context of Github, it is not uncommon for a developer to set two remotes

  • origin points to their own fork of a project
  • upstream is conventionally used to point to the project from which they forked.

This allows the owner of the fork to pull fixes and enhancements directly from the original project, thus keeping theirs in sync with it.

On Github, I have a fork of the official json-c repository. My local repo is setup thus:

$ git remote -v
origin  ssh://[email protected]/kdopen/json-c (fetch)
origin  ssh://[email protected]/kdopen/json-c (push)
upstream    [email protected]:json-c/json-c.git (fetch)
upstream    ssh://[email protected]/json-c/json-c.git (push)

I prepare changes in a local branch, regularly update my own fork with

$ git pull upstream master
$ git push origin master

and then rebase my own branches on the results.

If I have changes in my fork which I would like to see in the upstream version, then I create a "pull request" asking for them to accept my contribution. This process is referred to as "pushing a change upstream" which, for many projects, reflects the fact that its more work going upstream than down.

  • I don't think "head" comes from that analogy. Rather, it comes from the field of audio-visual technology, where it means "the part of a recording and playback device that reads data from and writes data to the storage medium."
    – Wildcard
    Jun 7, 2020 at 6:48
  • @Wildcard Possible. The "river" analogy has been around as long as I've been programming (coming up on 50 years), and so many flow-related terms are used in software that "head" makes sense and fits. Of course there is a widespread use of "head" in the sense you suggest: disk heads, tape heads, printer heads, and so on, and those are closely media (paper tape, for example) related ... though we had the "head" concept for computer hardware long before audio-visual technology moved off of acetate.
    – kdopen
    Jun 7, 2020 at 13:41

Upstream is not completely unique to open source, in the closed source world they just call it a vendor. It is however better in open source because you don't have to wait for the vendor to fix bugs which is why the river analogy is so popular (although not perfect as rivers are much more likely to only flow in one direction). A project can get software from many sources, put them together and distribute through a single distribution channel. Upstream is the projects you use to build your project. Which in most cases is more than one.

  • The terms "upstream" and "downstream" are apparently even in use outside of software development in the context of supply chain management in an analogous sense. Dec 15, 2017 at 13:32

Besides forks as @kdopen said, the "upstream" terminology also applies to Linux distributions.

In this case, the "upstream" is the actual developer of the project and the "downstream" is the packager. Distros have to add the packaging scripts and sometimes have to patch build scripts or source files; these are all sent downstream but only some are sent upstream.

There can even be multiple levels, e.g. an Ubuntu package based on a Debian package of a fork of a project (libjpeg-turbo for example).


Upstream/downstream is the directional term describing the flow of data.

For example in software development, when you use centralized revision control system (like SVN), you always commit changes upstream, in decentralized VCS (such as Git) there is no inherent/absolute "upstream" or "downstream" in the system, but you can choose how the data flows (so the main repository is used as "upstream").

In most of the software development projects, the code fixed/changes are usually committed/pushed to upstream repository (towards the production: dev, test, stage, live) and the database is pulled downstream (from the production into development environment).


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.