Contributing to DeepLabCut

Contributing to DeepLabCut#

Thanks for your interest in contributing to DeepLabCut! We welcome bug fixes, new features, documentation improvements, tests, and general maintenance contributions.

We especially encourage contributions from people from backgrounds that are underrepresented in open-source software. If you want to discuss an idea before opening a pull request, feel free to start a discussion or open an issue.

If you are new to GitHub, the GitHub Guides are a great place to start.

Ways to contribute#

You can help by:

  • Fixing bugs

  • Improving documentation

  • Adding tests

  • Improving examples

  • Refactoring or cleaning up code

  • Proposing or implementing new features

Development setup#

To work on DeepLabCut locally:

  1. Fork the repository.

  2. Clone your fork:

git clone https://github.com/<your-username>/DeepLabCut.git
cd DeepLabCut

  1. Create and activate a Python environment.

We recommend using the project’s development dependency group from pyproject.toml so you get the tools needed for local development (including formatting, linting, and testing).

For example, with uv:

uv sync --group dev

With pip (e.g. in a conda environment):

pip install -e . --group dev

If you use a different environment manager, install the package in editable/development mode together with the dev dependency group defined in pyproject.toml.

Working on the code#

Once your environment is ready, your local checkout is what Python will import.

If you want to verify that you are using the local source tree, you can run:

python -c "import deeplabcut; print(deeplabcut.__file__)"

Using ipython or Jupyter is completely optional—use whatever workflow you prefer.

If you change packaged resources or otherwise need to refresh the local installation, run:

./reinstall.sh

[!NOTE] This script automatically uninstalls the package, builds a new wheel using setup.py, and installs that wheel. It is not a simple pip install -e . because some resources are copied during installation and need to be refreshed.

Code style and pre-commit#

We use pre-commit to run formatting and other checks before code is committed.

Set it up once in your clone:

pre-commit install

Whenever you commit, pre-commit will run the configured checks.

Please run pre-commit before opening a pull request. This helps catch formatting, import ordering, whitespace, YAML, and other common issues early and accelerates code review greatly.

Tests#

Pull requests are validated in CI, and contributors are encouraged to run tests locally using:

pytest tests

in the project root before opening a pull request.

[!IMPORTANT] Heavier tests are also run automatically on GitHub, so this is not a strict requirement, but it can help catch issues early and speed up the review process.

Pull request guidelines#

When submitting a pull request, please:

  • Clearly describe what changed and why

  • Link any related issue(s)

  • Update docstrings and documentation when behavior changes

  • Add or update tests when appropriate

  • Include a small usage example when it helps reviewers understand and/or test the change

Smaller, focused pull requests are usually much easier to review than very large ones.

Draft pull requests#

We use draft pull requests to indicate work in progress. You may still request reviews and feedbacks on draft pull requests, and we encourage you to do so if you would like early feedback on your work. Please note that the draft status is in no way related to the perceived quality of the code or its potential for merging, but is simply a way to indicate that the work is not yet ready for final review and merging. Most pull requests exist for the majority of their lifetime as drafts, which is expected.

Documentation#

Documentation improvements are always welcome.

If your change affects users, please update the relevant docs, examples, or inline docstrings so the behavior is discoverable and easy to understand.

Code headers and notices#

If you need to standardize code headers, run:

python tools/update_license_headers.py

Contributors are requested not to update NOTICE.yml or LICENSE files.

Review process#

A maintainer will review your pull request. You do not need to supply a specific release timeline in your PR description—contributions are reviewed and merged as capacity allows.

If you have questions about where a change should go or how to structure it, opening a draft pull request is completely fine.

Need help?#

If you are unsure whether something is in scope, open an issue or draft PR and ask. We’d much rather help early than have you spend time on the wrong thing. We also welcome “Feature requests” issues if you would like to discuss implementation details or would like preliminary feedback.

Acknowledgments#

DeepLabCut is an open-source project and has benefited from many contributors over time, including:

We look forward to your contributions!

Contents