# Lightkurve: the friendly Python package for reading Kepler and TESS light curves

> Lightkurve is a community-developed, open-source Python package for analysing astronomical flux time series, in particular the pixels and lightcurves from NASA's Kepler and TESS exoplanet missions. Its stated purpose is to lower the barrier for students, astronomers and citizen scientists, and it does that by packaging a large stack of astronomy dependencies behind one API with tutorials attached.

**lightkurve/lightkurve** — A friendly package for Kepler & TESS time series analysis in Python.

- Repository: https://github.com/lightkurve/lightkurve
- Website: https://lightkurve.github.io/lightkurve/
- Stars: 545 · Forks: 205
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/lightkurve-lightkurve

## What the package is for

Lightkurve is described as a community-developed, open-source Python package which offers a beautiful and user-friendly way to analyze astronomical flux time series data, in particular the pixels and lightcurves obtained by NASA's Kepler and TESS exoplanet missions.

The goal is stated plainly in the next paragraph. The package aims to lower the barrier for students, astronomers, and citizen scientists interested in analyzing Kepler and TESS space telescope data. It does this by providing high-quality building blocks and tutorials which enable both hand-tailored data analyses and advanced automated pipelines.

That last clause is the important one, because it describes two different audiences and two different workflows. A hand-tailored analysis is the case where you load a target, look at its light curve, maybe detrend it, and answer a question about it. An automated pipeline is the case where you run the same sequence over thousands of targets and need the code to be composable and the intermediate steps to be inspectable. Lightkurve's design has to serve both, and a lot of its API shape follows from that.

The stack underneath is large and the package hides it. The pyproject lists astropy for the astronomy core, scipy, numpy and pandas for the numerics, matplotlib for plotting, astroquery for querying the archives, beautifulsoup4 and requests for the web access that archive queries need, tqdm for progress bars, uncertainties for propagating error bars through a fit, patsy for formula parsing, scikit-learn for the machine learning parts, bokeh for interactive plots, s3fs for reading from object storage, and fbpca for principal component analysis.

The primary language is Python, the licence is MIT, the default branch is main, and the homepage is lightkurve.github.io/lightkurve. The recent releases are v2.6.0 from 2026-04-16, v2.5.1 from 2025-05-20 and v2.5.0 from 2024-08-29, and the last push was on 2026-10-20 with the project not archived. The project classifies itself as Development Status 5, Production/Stable, and the manifest version reads 2.6.1dev, so the released version and the working version differ by a patch.

## Installing it, and the three routes the quickstart offers

The quickstart lives on the documentation site rather than in the repository, and the repository gives the install commands in reStructuredText form.

The easiest way to install Lightkurve and all of its dependencies is to use the pip command, which is a standard part of all Python distributions:

```bash
    $ python -m pip install lightkurve --upgrade
```

The --upgrade flag is optional, but recommended if you already have Lightkurve installed and want to upgrade to the latest version. And depending on the specific Python environment, you may need to replace python with the correct Python interpreter, for example python3.

The second route is the development version, installed straight from the main branch on GitHub:

```bash
    $ git clone https://github.com/lightkurve/lightkurve.git
    $ cd lightkurve
    $ python -m pip install .
```

The third is an editable install, which enables the installed version to immediately reflect changes made in the source tree:

```bash
    $ python -m pip install poetry
    $ poetry install
```

Three routes is a sensible spread, and the middle one is worth a comment. A plain pip install of a git clone gives you a snapshot of the main branch, which means the code you are running may be mid-change between releases. The editable install with poetry is the one that actually reflects your edits, and it is the route a contributor should be using.

That the development install goes through poetry while the published package is installed with pip is the packaging arrangement, and it is visible in the repository. The pyproject.toml has a tool.poetry section with the project metadata, and the Makefile runs every check through poetry run, so poetry is the development toolchain rather than just the build backend.

The environment requirements are also in the manifest, and they are where the version handling gets interesting. Python is ^3.9. numpy is constrained differently depending on the interpreter: at least 1.18 for Python below 3.12 and at least 1.26 for 3.12 and above. scipy is at least 1.7 for Python below 3.14. And urllib3 and memoization are pinned to Python below 4.0, with a comment on urllib3 explaining it is necessary to make requests work on py310.

That last comment is a good example of the kind of detail that only appears in a real project, where a transitive dependency broke on a specific interpreter version and the fix was a constraint rather than an upstream patch.

## The dependency list, and what it says about the scope

The dependencies are worth reading as a statement of what Lightkurve covers, because each one is a capability.

astropy at 5.0 or newer is the foundation, providing units, coordinates, FITS file handling and the astronomy object model. Everything else sits on top of it, which is why the package is a wrapper rather than a replacement.

astroquery at 0.3.10 or newer is how you reach the archives. Kepler and TESS data are served from public archives that are queried rather than downloaded wholesale, and astroquery is the layer that speaks to them. beautifulsoup4 and requests are in the list because archive access involves HTML forms and web pages as well as APIs, and the fact that both are direct dependencies rather than transitive ones tells you the package does its own scraping rather than delegating it.

numpy, scipy and pandas are the numerical core. uncertainties at 3.1.4 or newer handles error propagation, and that is a small detail with a big consequence: a light curve from a space telescope has per-point uncertainties, and any science you do with it has to carry them, so a package that treats them as an afterthought is not usable for real work.

patsy at 0.5.0 or newer is the formula parser, used where a model is written as an expression rather than a function call. scikit-learn at 0.24.0 or newer is for the machine learning side, and fbpca at 1.0 or newer is principal component analysis, which is what you use to find variability in a set of light curves at once.

bokeh at 2.3.2 or newer is the interactive plotting layer, and the comment on that line is specific: bokeh v2.3.2+ requirement due to a pull request reference, 1428. So the constraint was raised for a stated reason, and the reason is recorded in the manifest where a maintainer will see it.

s3fs at 2024.6.1 or newer is for reading from object storage, which is how a large archive-hosted dataset is loaded without a full local copy. tqdm at 4.25.0 or newer gives progress bars, and in a package that downloads telescope data over the network, a progress bar is a user interface element rather than a decoration.

Then there is nifty-ls, marked as an optional dependency at 1.0 or newer, and the manifest notes that it is a run-time optional dependency. So there is at least one algorithm you can install or not, which is the shape of a package that is trying to stay installable across a wide set of environments.

## The Makefile, and what the checks tell you about the project

The Makefile is short and it tells you what a change to this repository has to pass.

```makefile
.PHONY: all clean pytest coverage flake8 black mypy isort

CMD:=poetry run
PYMODULE:=src
TESTS:=tests

# Run all the checks which do not change files
all: mypy pytest flake8

# Run the unit tests using `pytest`
pytest:
	$(CMD) pytest $(PYMODULE) $(TESTS)

# Generate a unit test coverage report using `pytest-cov`
coverage:
	$(CMD) pytest --cov=$(PYMODULE) $(TESTS) --cov-report html

# Lint the code using `flake8`
flake8:
	$(CMD) flake8 $(PYMODULE) $(TESTS)
```

The all target is mypy, pytest and flake8, described as all the checks which do not change files. The pytest target runs the test suite over both the module and the tests directory, and the coverage target adds --cov with an HTML report, so coverage is a first-class thing rather than something you configure yourself.

The variables at the top are worth a glance. CMD is poetry run, so every check goes through the poetry environment rather than whatever happens to be on your shell's path. PYMODULE is src and TESTS is tests, which is the src/ layout with tests at the top level rather than nested inside the package.

The repository tree matches that. There is a src/ directory for the package, a tests/ directory, a docs/ directory, and a pyproject.toml, plus a tox.ini for running the checks across environments, a Makefile, a CHANGES.rst, a CITATION file, an AUTHORS.rst, and CONTRIBUTING.rst alongside a CODE_OF_CONDUCT.md. There is also a .git-blame-ignore-revs file, which lists commits that should be ignored when running git blame, usually a reformatting or dependency-bump commit that would otherwise make the history unreadable.

Two files in that list are specific to this project and worth calling out. CHANGES.rst is a changelog, which is what you expect from a package with a citation page. And CITATION is a machine-readable citation file, which is the convention for a package that asks to be cited in a paper, which this one explicitly does: if you find Lightkurve useful in your research, please cite it and give us a GitHub star.

The include list in the pyproject matches, listing AUTHORS.rst, CHANGES.rst, CONTRIBUTING.rst and CITATION as files to ship in the distribution. That is a small thing, but it is the difference between a user being able to cite the package and not.

The project also has a Zenodo DOI badge, which is the archive that gives a software citation a permanent identifier. For a research package maintained partly by a NASA mission support centre, that is the mechanism that makes the work citable in the literature, and it is a detail a lot of research software never gets round to.

## How to evaluate it, and what to check first

There are four things to consider.

First, whether the dependency stack is acceptable for your environment. Lightkurve pulls in astropy, scipy, pandas, scikit-learn, bokeh and astroquery, and it constrains several of them by Python version. If you already work in a scientific Python environment this is unremarkable. If you are installing into a minimal environment, or if you have a pinned scientific stack of your own, the constraints in the manifest are the thing to read, particularly the numpy split at Python 3.12 and the scipy split at Python 3.14.

Second, whether you want the archive access in the package or not. astroquery, requests and beautifulsoup4 are there because Lightkurve queries the public archives, which is convenient and is also the part that makes the package slow and network-dependent for the tasks that need it. The manifest marks some dependencies as optional run-time extras, so the question of what you can leave out is worth reading about in the install documentation.

Third, how you will use it, because the two workflows are served differently. If you are analysing a handful of targets interactively, the quickstart and the tutorials are the whole story, and the package is genuinely friendly in that mode. If you are running a pipeline over thousands of targets, the parts that matter are the composability of the steps, the inspectability of the intermediate products, and the ability to run without a human in the loop, and the README's promise of building blocks for both is the claim to test against your own pipeline.

Fourth, the maintenance state. The last push was on 2026-10-20 and the newest release is v2.6.0 from 2026-04-16, with the manifest at 2.6.1dev. The earlier releases are further apart, v2.5.1 from 2025-05-20 and v2.5.0 from 2024-08-29, so the cadence is irregular rather than metronomic, which is normal for a package whose maintenance comes from a mix of a stable community and a mission support centre.

What you get is one of the more complete packages in its field, with a documentation site, a DOI, a citation file, a changelog, type checking in the build, and a stated audience that starts with students and citizen scientists. The cost is the dependency weight, and the honest caveat is that the tutorials assume you want to do astronomy rather than that you want a general time series library, because the assumptions about units, apertures and flux are baked in.

## Conclusion

Adopt Lightkurve if you are working with Kepler or TESS light curves and want the archive queries, the aperture tools, the plotting and the error propagation in one place with tutorials attached, because the alternative is assembling the same stack yourself from astropy and astroquery. Do not adopt it for general time series work, since the package assumes astronomy in its units, apertures and flux conventions, and check the version constraints before installing, because numpy and scipy are pinned differently depending on your Python version and the full dependency set is large. Before you commit, read the manifest constraints for your interpreter, decide which of the optional run-time extras you actually need since they determine how much of the network-facing stack gets pulled in, and run the project's own checks, which are mypy, pytest and flake8 through poetry run, so you know the baseline before you change anything.

## FAQ

### What is Lightkurve?

It is a community-developed, open-source Python package offering a user-friendly way to analyze astronomical flux time series data, in particular the pixels and lightcurves obtained by NASA's Kepler and TESS exoplanet missions. It is MIT licensed, and the documentation is at lightkurve.github.io/lightkurve.

### How do I install Lightkurve?

The easiest route is to run python -m pip install lightkurve --upgrade, replacing python with python3 if that is your interpreter. To work from the development version you can clone the repository and run python -m pip install ., and for an editable install that reflects changes in the source tree you use python -m pip install poetry followed by poetry install.

### What does Lightkurve depend on?

astropy, scipy, numpy, pandas, matplotlib, astroquery, beautifulsoup4, requests, urllib3, tqdm, uncertainties, patsy, scikit-learn, fbpca, bokeh and s3fs, with nifty-ls available as an optional dependency. Several are constrained by Python version, and numpy is required at 1.18 or newer below Python 3.12 and 1.26 or newer from 3.12.

### Who maintains Lightkurve and how do I get in touch?

It is an open source community project created by its authors, with the manifest naming Geert Barentsen and the TESS Science Support Center as authors. The best way to contact them is to open an issue or to e-mail tesshelp@bigbang.gsfc.nasa.gov, and they ask that you include a self-contained example demonstrating the problem.

### How do I cite Lightkurve?

The README asks that you cite the package and give the project a GitHub star if you find it useful, and points to the citation instructions on the documentation site. The repository ships a CITATION file and the project has a Zenodo DOI badge, which gives the software citation a permanent identifier.

## Sources

- [License: MIT](https://github.com/lightkurve/lightkurve/blob/main/LICENSE)
- [lightkurve/lightkurve on GitHub](https://github.com/lightkurve/lightkurve)
- [Project website](https://lightkurve.github.io/lightkurve/)
- [README](https://github.com/lightkurve/lightkurve/blob/main/README.md)
- [Releases](https://github.com/lightkurve/lightkurve/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lightkurve-lightkurve