Difference between composer prefer-dist and prefer-source?

Question

Looking at the help for PHP Composer's install command, I see the following two options

$ composer help install
Options:
 --prefer-source            Forces installation from package sources when possible, including VCS information.
 --prefer-dist              Forces installation from package dist even for dev versions.

What's a "dist" installation? I poked around the composer site and Google but there didn't seem to be anything that addressed this (So I assume it's something core and obvious to folks familiar with Composer — apologies for the newbie question)

I'm assuming --prefer-source is where Composer will ask Packagist for the repository location, and then checkout/clone/export/etc. the project itself.

If so, then where does --prefer-dist download from? What does it download?

I'm *completely guessing* that "dist" is short for "distribution" — nickb, Apr 25 '13 at 01:54
@nickb That's what the docs online have led me to believe — but nothing seems to describe what a distribution is. — Alana Storm, Apr 25 '13 at 01:57
Check [their example for Smarty](http://getcomposer.org/doc/05-repositories.md#package-2). It looks like "dist" would be a stable distribution that the dependency is publishing, where "source" would be a latest snapshot, potentially directly from their source control. — nickb, Apr 25 '13 at 02:01
Please kindly reconsider changing the accepted answer, as the correct answer in mine. — Peyman Mohamadpour, May 05 '20 at 08:48

Ross Smith II · Accepted Answer · 2013-04-25T03:33:14.983

According to http://getcomposer.org/doc/03-cli.md, the --prefer-source option will prefer to create a package directory that is a "version control repository". This is equivalent to you typing:

$ git clone ...

or

$ svn checkout ...

The --prefer-dist option will prefer to create a non-"version control repository", which is equivalent to you typing:

$ git clone ... ; rm -fr dir/.git

or

$ svn export ...

Also, you can define separate repos for source and dist in your composer.json. Here's an example:

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "joshuaclayton/blueprint-css",
                "version": "master",
                "source": {
                    "url": "git://github.com/joshuaclayton/blueprint-css.git",
                    "type": "git",
                    "reference": "master",
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "fiftyone/mobi-lite-php",
                "version": "2013.03.06",
                "dist": {
                    "url": "http://iweb.dl.sourceforge.net/project/fiftyone/51Degrees.mobi-Lite-2013.03.06.php.zip",
                    "type": "zip"
                },
            }
        }
    ]
}

NOTE: for whatever reason, when I use --prefer-dist, I sometimes get errors such as

Fatal error: Cannot redeclare class Zend_Db_Adapter_Pdo_Abstract in ...

which do not appear when I use --prefer-source. For this reason, I only use --prefer-source, until I figure out the cause of this issue.

`--prefer-dist` is not equivalent to a git checkout minus the `.git` directory, although it is close enough. As you noted, you can separately define the source and distribution URL of a package; if you don't, it will result in a git archive instead of a git checkout. That means the [`export.ignore`](https://git-scm.com/docs/gitattributes#_export_ignore) option of `.gitattributes` will be honored - if the project bothered to set it properly, unit tests and similar files that are not necessary (and sometimes even risky) in a production site will usually be omitted. — Tgr, Jul 24 '20 at 23:20
Also, `--prefer-dist` is a bit faster and does not require Git to be installed. — Tgr, Jul 24 '20 at 23:21
Thanks for your response, it helped a lot. Note: structure of repositories has slightly changed: https://getcomposer.org/doc/05-repositories.md#package-2. — Roman Kliuchko, May 31 '21 at 09:20
Is it possible to remove the note with the error - this seems entirely unrelated to the question and I assume is resolved now - it's been almost 10 years. — Sybille Peters, Jun 18 '22 at 16:22

Peyman Mohamadpour · Answer 2 · 2021-11-02T07:47:29.920

30

I don't admire, or even approve the provided answer, as it does not address the question. So despite of it being a bit too old, I am posting this answer for any further reference to this question.

Basics:

Normally composer deals with tags (like 1.2.7), but that is not the case all the time. You may also require a branch (like dev-master) as a dependency.

If you want composer to require a tag, it just copies the files on your local (somewhere in your vendor directory).
If you want composer to checkout a branch instead of a tag, there is chance (composer's rational assumption), you want to develop it (thus making changes), so composer clones the repository on your local (again, somewhere in the vendor directory).

So, what?!

Question:

What if you want to require a tag, but still be able to develop it on your local?

Answer:

use --prefer-source along with your composer require or composer update commands:

composer require symfony/symfony:3.4.* --prefer-source

Question:

What if you want to require a most new development branch, but you just want to get the new stuff and don't want to get engaged in its development?

Answer:

use --prefer-dist along with your composer require, composer update commands:

composer require symfony/symfony:dev-master --prefer-dist

edited Nov 02 '21 at 07:47

answered Oct 09 '17 at 08:22

Peyman Mohamadpour

17,954
24
89
100

1

Small typo `--prefer-srouce` should be `--prefer-source` – Craig London Mar 16 '18 at 20:11
And 'dist' is default if you omit those flags? – robsch May 09 '19 at 14:18
You can't specify an individual package with `composer install`. If you want to specify source vs dist at a package level use `preferred-install` in composer.json – Jeremy Gallant Jul 28 '21 at 12:36
Maybe the accepted answer has been updated. How does it not answer the question? – Frank Robert Anderson Mar 09 '22 at 23:18
@FrankRobertAnderson I think you answered your own question by yourself! – Peyman Mohamadpour Mar 16 '22 at 00:33
Looks like the suggest an edit queue is full. Maybe if you removed that whole part about how **bad** the accepted answer is a question like mine wouldn't be needed. – Frank Robert Anderson Apr 06 '22 at 21:39

score 9 · Answer 3 · edited Jun 20 '20 at 09:12

As clearly stated in Composer's Documentation:

In fact, internally Composer sees every version as a separate package. While this distinction does not matter when you are using Composer, it's quite important when you want to change it.

and,

Dist: The dist is a packaged version of the package data. Usually a released version, usually a stable release.

Source: The source is used for development. This will usually originate from a source code repository, such as git. You can fetch this when you want to modify the downloaded package.

so,

Packages can supply either of these, or even both. Depending on certain factors, such as user-supplied options and stability of the package, one will be preferred.

If you're checking out a branch, it's assumed that you want to work on the branch and Composer actually clones the repo into the correct place in your vendor directory.

For tags, it just copies the right files without actually cloning the repo.

I did `php composer.phar require phpmailer/phpmailer` and from the response it seems it tried to download from dist but zip commands were missing. So it went on and tried to download from source which succeeded. I wonder if that means that when it downloads from dist it gets a zipped file but from source it does not? — user3425506, Sep 06 '22 at 10:50

Difference between composer prefer-dist and prefer-source?

3 Answers3

Basics:

So, what?!

Question:

Answer:

Question:

Answer:

Linked