How to open source your Python library

This 12-step checklist will ensure a successful launch.
253 readers like this.
open source button on keyboard

You wrote a Python library. I'm sure it's amazing! Wouldn't it be neat if it was easy for people to use it? Here is a checklist of things to think about and concrete steps to take when open sourcing your Python library.

1. Source

Put the code up on GitHub, where most open source projects happen and where it is easiest for people to submit pull requests.

2. License

Choose an open source license. A good, permissive default is the MIT License. If you have specific requirements, Creative Common's Choose a License can guide you through the alternatives. Most importantly, there are three rules to keep in mind when choosing a license:

  • Don't create your own license.
  • Don't create your own license.
  • Don't create your own license.


Put a file called README.rst, formatted with ReStructured Text, at the top of your tree.

GitHub will render ReStructured Text just as well as Markdown, and ReST plays better with Python's documentation ecosystem.

4. Tests

Write tests. This is not useful just for you: it is useful for people who want to make patches that avoid breaking related functionality.

Tests help collaborators collaborate.

Usually, it is best if they are runnable with pytest. There are other test runners—but very little reason to use them.

5. Style

Enforce style with a linter: PyLint, Flake8, or Black with --check. Unless you use Black, make sure to specify configuration options in a file checked into source control.

6. API documentation

Use docstrings to document modules, functions, classes, and methods.

There are a few styles you can use. I prefer the Google-style docstrings, but ReST docstrings are an option.

Both Google-style and ReST docstrings can be processed by Sphinx to integrate API documentation with prose documentation.

7. Prose documentation

Use Sphinx. (Read our article on it.) A tutorial is useful, but it is also important to specify what this thing is, what it is good for, what it is bad for, and any special considerations.

8. Building

Use tox or nox to automatically run your tests and linter and build the documentation. These tools support a "dependency matrix." These matrices tend to explode fast, but try to test against a reasonable sample, such as Python versions, versions of dependencies, and possibly optional dependencies you install.

9. Packaging

Use setuptools. Write a and a setup.cfg. If you support both Python 2 and 3, specify universal wheels in the setup.cfg.

One thing tox or nox should do is build a wheel and run tests against the installed wheel.

Avoid C extensions. If you absolutely need them for performance or binding reasons, put them in a separate package. Properly packaging C extensions deserves its own post. There are a lot of gotchas!

10. Continuous integration

Use a public continuous integration runner. TravisCI and CircleCI offer free tiers for open source projects. Configure GitHub or other repo to require passing checks before merging pull requests, and you'll never have to worry about telling people to fix their tests or their style in code reviews.

11. Versions

Use either SemVer or CalVer. There are many tools to help manage versions: incremental, bumpversion, and setuptools_scm are all packages on PyPI that help manage versions for you.

12. Release

Release by running tox or nox and using twine to upload the artifacts to PyPI. You can do a "test upload" by running DevPI.

Moshe sitting down, head slightly to the side. His t-shirt has Guardians of the Galaxy silhoutes against a background of sound visualization bars.
Moshe has been involved in the Linux community since 1998, helping in Linux "installation parties". He has been programming Python since 1999, and has contributed to the core Python interpreter. Moshe has been a DevOps/SRE since before those terms existed, caring deeply about software reliability, build reproducibility and other such things.

1 Comment

Thanks, this was a good pointer. I have created few packages, didn't published any as of now. This post is a direction I needed.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.