Question on package vs modules

I’ve read the official documentation on packages and modules, but I get the impression the two concepts get conflated. Can someone say if the following statements are true or false, and if false then why:

  1. A single Github repo may host 1 or more packages.
  2. A single package with name X will always contain a file X.jl.
  3. X.jl will always define a module named X
  4. You can’t have other top-level modules in a single package (see here and here).

Thank you


At least for me:
1 repo, 1 package.
The structure can be profitably left up to User Guide · PkgTemplates.jl. PkgTemplates will generate your package with all the right components.
And, yes, package X.jl should have an src directory with “X.jl” in it.
I always have a top module called X for the package.

But things may be rather different for projects. These do not need to have this relatively rigid structure.

1 Like

It was my understanding that packages are projects. Although projects need not be packages.

Correct. That was a slip up. Please replace projects with applications.
More here, and here.

If you have a module for things you do on your own, leaving it as only a module and putting it in your LOAD_PATH makes sense. I have a few little things like that.

If you plan on sharing the material with others or, more seriously, using it to support a journal `publication, then it makes a lot of sense to put it in a project or application with the right .toml files. That make the dependencies clear and helps your colleagues/readers/collaborators reproduce results. The escalation from module to application/project almost surely means you have to learn how github supports that stuff, learn enough about pkg to build the .toml files, and put X.jl in the right place.

If your project becomes a bigger deal, say a tool for a class you teach, a group you lead, or a book, then making it a package is a good idea so you can do CI and distribute it more easily.

This is, of course, my opinion as of today. I’ve changed my mind on this a couple times in the past.


2-4 are correct, though you should understand that they are conventions of the package manager rather than built into the language itself. To me that seems exactly right: the package manager should enforce certain conventions, but the language keeps the concepts orthogonal.

1 should be amended to “0 or more modules.” You can put a script in a repo and push it to GitHub.