How to package Python research code so others can install it
A package gives your research code one home, one version history and one way in. This guide covers the layout, the pyproject.toml file, testing, releases, citation and when to publish on PyPI or conda-forge.

- Package code once the same functions are used in more than one project, by more than one person, or by a reviewer.
- Put the reusable library under src/, describe it in pyproject.toml, and keep figure scripts and notebooks outside the package.
- Use loose dependency ranges in the package and exact pins (a lockfile or container) for the analysis behind a paper.
- Tag every release, note any change that alters numerical results, and add CITATION.cff so the package can be cited.
Packaging Python research code means turning a folder of scripts into something other people can install with one command, usually pip install. In practice that takes three things: a src/ folder holding your reusable functions, a pyproject.toml file describing the package and its dependencies, and a version number you change on purpose. Everything else in this guide (tests, a command-line entry point, a citation file, a PyPI release) builds on those three.
Most research projects reach this point by accident. A script written for one figure gets copied into a second project, then a colleague asks for it, then a student changes it and the two copies drift apart. A package gives that code one home, one version history and one way in. It also makes the analysis behind a paper easier to rerun, because the paper can name the exact version it used.
Packaging is also the moment many lab tools stop being only research code, because outside users bring issues, dependency updates and feature requests. Some groups bring in a campus research software engineer for that. Others hire external python software development services for work that looks like ordinary product engineering, such as an API, a web front end or a release pipeline. The scientific decisions stay with the researchers either way.
When should you package research code?
Package your code when the same functions are used in more than one place. That might be two of your own projects, two people in your lab or a reviewer who needs to run your analysis. If a script is used once, for one figure, a clean project folder and a pinned environment are enough. Our guide to organising a research project folder covers that simpler case.
These signs mean a package will save you time:
- You copy files between projects. Each copy is a fork that will drift.
- You edit
sys.pathto import your own code. That breaks as soon as the folder moves. - Collaborators ask "which version did you use?" and nobody can answer with certainty.
- A journal or reviewer wants to run the code. An installable package with tests is far easier to check.
- The code implements a method that other groups could apply to their own data.
A package does not have to be public or polished. A private package installed from your lab's Git repository already solves most of the problems above.
What does a research package look like?
A research package separates the reusable library from the analysis that uses it. The library goes under src/; the scripts and notebooks that produce your paper's figures stay outside it and import the library like any other dependency. A minimal layout looks like this:
soilflux/
├── pyproject.toml
├── README.md
├── LICENSE
├── CITATION.cff
├── src/
│ └── soilflux/
│ ├── __init__.py
│ ├── io.py
│ └── models.py
├── tests/
│ └── test_models.py
└── analysis/
└── figure_3.py
The src/ layout is the default in the Scientific Python Development Guide and the Python Packaging User Guide. It forces your tests to run against the installed package rather than whatever files happen to sit in the working directory, which catches missing files and broken imports before your users do.
Keep analysis/ out of the package. Figure scripts change with every revision of a paper and depend on local data paths. The library should change only when the method changes.
How do you write pyproject.toml?
Write pyproject.toml as the single description of your package: how to build it, what it is called, which Python versions it supports and what it needs to run. It replaces the older setup.py and setup.cfg files, and every modern build tool reads it. A complete starting point for a research package fits on one screen:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "soilflux"
version = "0.3.0"
description = "Models for soil CO2 flux from chamber measurements"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
authors = [{ name = "A. Researcher", email = "a.researcher@example.edu" }]
dependencies = ["numpy>=1.24", "pandas>=2.0", "scipy"]
[project.optional-dependencies]
plot = ["matplotlib"]
[project.scripts]
soilflux = "soilflux.cli:main"
[dependency-groups]
test = ["pytest", "pytest-cov"]
Each section has a clear job. The table below explains what to put in each one and the mistake researchers make most often.
| Section | What it does | Common mistake |
|---|---|---|
[build-system] | Names the backend that builds the package: Hatchling, Setuptools, Flit or PDM | Spending days choosing. They all read the same standard metadata |
[project] | Name, version, description, license, Python range and authors | Leaving out requires-python, so users on old Python get cryptic errors |
dependencies | What the package needs to run | Pinning exact versions such as numpy==1.24.3, which blocks installation alongside other tools |
optional-dependencies | Extras users can request, such as plotting or GPU support | Making heavy libraries mandatory when only one function uses them |
[project.scripts] | Creates a command-line program on install | Asking users to run python path/to/script.py instead |
[dependency-groups] | Tools for developers only: tests, linters, docs | Listing pytest as a runtime dependency |
The Python Packaging User Guide page on pyproject.toml documents every field. The license field takes an SPDX identifier such as MIT or BSD-3-Clause; if you have not chosen one yet, our licence primer for research code walks through the options. Dependency groups are a newer standard (PEP 735), supported by recent releases of pip and uv.
Why loose dependencies in the package and pins for the paper?
Use loose version ranges in the package and exact pins for the analysis that produced a result. These are two different jobs, and mixing them causes most of the installation pain in research software.
- The package declares what it can work with, for example
pandas>=2.0. That lets other people install it next to their own tools. - The paper's analysis records exactly what it did run with, in a lockfile, a Conda environment file or a container image, stored with the analysis scripts.
Reviewers rerunning Figure 3 use the lockfile. A lab elsewhere using your method installs the package and gets whatever compatible versions their environment already has. Our guide to reproducible environments covers lockfiles and containers in detail.
How do you install and test it while you work?
Install the package in editable mode while you develop it. From the project folder, run pip install -e . (or uv pip install -e .). Python then imports your code straight from src/, so changes take effect without reinstalling, and your analysis scripts can import soilflux from anywhere.
Add tests next, even a few. Start with one test per public function that checks a known answer, for example a published value or a hand-calculated case.
Then run the tests automatically on every change with a continuous integration service such as GitHub Actions or GitLab CI, across the oldest and newest Python versions you claim to support. Our guide to testing research code shows which tests catch real scientific errors rather than just raising coverage numbers.
Before you share the package, check it the way a stranger would meet it:
- Create a fresh virtual environment with nothing else installed.
- Run
python -m buildto produce the wheel and source distribution. - Install the wheel from the
dist/folder, not the editable copy. - Run the tests and one command from the README.
If any step fails, a user would have hit the same failure. Missing data files, forgotten dependencies and import paths that only work from the project folder all show up here.
How should you version and release?
Give every release a version number and a Git tag, and change the number on purpose. Most scientific packages use semantic versioning, where each part of a number such as 1.4.2 has a meaning:
- Third number: bug fixes.
- Second number: new features that keep existing code working.
- First number: changes that can alter existing results or break existing code.
Before 1.0, say in the README that results may change between minor versions.
For research code, add one rule: any change that alters a numerical result gets a release note saying so. A user comparing results across versions needs to know whether a difference is their data or your fix.
Tools such as hatch-vcs or setuptools-scm can read the version from Git tags, so the number in the package always matches the tagged commit. Each tagged release is also the natural thing to archive. Our guide to archiving code with a DOI explains how a Zenodo integration turns every release into a citable snapshot.
How do you make the package citable?
Add a CITATION.cff file to the repository root. The Citation File Format is plain YAML listing authors, title, version, DOI and a preferred reference such as the paper describing the method. GitHub shows a "Cite this repository" button when the file is present, and Zenodo reads it when archiving a release.
Keep the version in CITATION.cff in step with pyproject.toml, and update the DOI after each archived release. If the package implements a published method, list that paper as the preferred citation so credit goes where reviewers expect it. Our guide to citing software in papers covers the other side: how users should cite your package in their own work.
Should you publish on PyPI or conda-forge?
Publish on PyPI when people outside your group will install the package, and add conda-forge when your users mostly work in Conda environments or need compiled dependencies. A lab-internal package can stay on Git and be installed with pip install git+https://….
| Route | Best for | Effort |
|---|---|---|
| Install from Git | One lab, a few collaborators, early versions | None beyond a tagged repository |
| PyPI | Anyone using pip or uv; the default for public Python libraries | An account, a unique name, a release workflow |
| conda-forge | Users in Conda environments, packages with C or Fortran dependencies | A recipe submitted for review, then mostly automated updates |
For PyPI, practise on TestPyPI first, then set up trusted publishing so your CI pipeline uploads releases without a stored password or API token. For conda-forge, a tool called grayskull can generate a first recipe from your PyPI release.
If you want outside feedback on the package itself, pyOpenSci runs community peer review for scientific Python packages, and its Python packaging guide sets out what reviewers look for. The Journal of Open Source Software reviews the software and gives it a citable paper; see our guide to publishing in JOSS.
What happens when the package outgrows the lab?
When other groups depend on your package, maintenance becomes a standing commitment. Issues arrive, new Python and NumPy releases break things, and someone asks for a web interface or an API for non-programmers. None of that is research, and it rarely fits into a PhD timeline.
Plan for it early. Name a maintainer and a backup, write down how releases are made, and keep the scientific core small and well tested so that others can contribute without understanding everything. If the work grows beyond what the group can carry, a research software engineer, either on staff or shared through your institution, is the usual next step. Our guide to working with research software engineers explains how to involve one well.
What to do this week: package one module
You do not need to package the whole project at once. Start small:
- Pick the most-copied file. Choose the module that already appears in two projects.
- Move it into
src/<name>/and add the minimalpyproject.tomlshown above. - Install it with
pip install -e .and change one analysis script to import it. - Write one test that checks a known answer, and tag the commit as
v0.1.0.
That is a real package. Everything else in this guide can be added one release at a time.
Questions about packaging research code
Do I need to publish my package on PyPI?
No. A package installed from your lab's Git repository already gives you one source of truth, versioned releases and clean imports. Publish on PyPI when people outside your group will install it regularly.
Which build backend should I choose for a research package?
Any of the common ones works: Hatchling, Setuptools, Flit or PDM. They all read the same standard pyproject.toml metadata. Hatchling is the default in the Scientific Python Development Guide. If your package includes C, C++ or Fortran code, look at scikit-build-core or meson-python, which the same guide covers.
Is requirements.txt still needed if I have pyproject.toml?
Not for the package. Runtime dependencies belong in pyproject.toml. A pinned requirements or lock file is still useful for the analysis behind a paper, where you want to record the exact versions that produced a result.
Can I package code that lives in Jupyter notebooks?
Move the reusable functions out of the notebooks into modules under src/, then import them back into the notebooks. The notebooks stay as analysis and documentation; the package holds the logic that other projects reuse.
How do I make sure the package version matches what my paper used?
Tag the release in Git, archive it with a DOI, and record the version in your analysis environment file. Tools such as hatch-vcs or setuptools-scm read the version from the Git tag, so the number cannot drift from the code.
Keep reading. More from the desk.
Reproducible environments for research code
Sharing your code is step one. Making sure it still runs on someone else's machine, next year, is step two. The tools are mature. The hard part is choosing the right level of effort.
Testing research code: where to start
You already check your results by hand. Automated tests do the same checks every time the code changes, so a quiet bug gets caught the same day instead of in review.
Archive your code with a DOI
A GitHub link in a paper is a bet that the repository will still exist, unchanged, years from now. Archiving a release with a DOI removes the bet. It takes about fifteen minutes the first time.