Thanks for taking the time to contribute! We appreciate all contributions, from reporting bugs to implementing new features. If you're unclear on how to proceed after reading this guide, please contact us on Discord.
Before creating a bug report, please check that your bug has not already been reported, and that your bug exists on the latest version of Polars. If you find a closed issue that seems to report the same bug you're experiencing, open a new issue and include a link to the original issue in your issue description.
Please include as many details as possible in your bug report. The information helps the maintainers resolve the issue faster.
We use GitHub issues to track bugs and suggested enhancements. You can suggest an enhancement by opening a new feature request. Before creating an enhancement suggestion, please check that a similar issue does not already exist.
Please describe the behavior you want and why, and provide examples of how Polars would be used if your feature were added.
Contributing to the codebase
Picking an issue
Pick an issue by going through the issue tracker and finding an issue you would like to work on. Feel free to pick any issue with an accepted label that is not already assigned. We use the help wanted label to indicate issues that are high on our wishlist.
If you are a first time contributor, you might want to look for issues labeled good first issue. The Polars code base is quite complex, so starting with a small issue will help you find your way around!
If you would like to take on an issue, please comment on the issue to let others know. You may use the issue to discuss possible solutions.
Setting up your local environment
Polars development flow relies on both Rust and Python, which means setting up your local development environment is not trivial. If you run into problems, please contact us on Discord.
Note that if you are a Windows user, the steps below might not work as expected; try developing using WSL.
Under native Windows, you may have to manually copy the contents of
py-polars/toolchain.toml, as Git for Windows may not correctly handle symbolic links.
Start by forking the Polars repository, then clone your forked repository using
git clone https://github.com/<username>/polars.git
First, install Rust using rustup. After the initial installation, you will also need to install the nightly toolchain:
rustup toolchain install nightly --component miri
Next, install Python, for example using pyenv.
We recommend using the latest Python version (
Make sure you deactivate any active virtual environments or conda environments, as the steps below will create a new virtual environment for Polars.
You will need Python even if you intend to work on the Rust code only, as we rely on the Python tests to verify all functionality.
Finally, install dprint. This is not strictly required, but it is recommended as we use it to autoformat certain file types.
You can now check that everything works correctly by going into the
py-polars directory and running the test suite
(warning: this may be slow the first time you run it):
This will do a number of things:
- Use Python to create a virtual environment in the
- Use pip to install all Python dependencies for development, linting, and building documentation.
- Use Rust to compile and install Polars in your virtual environment. At least 8GB of RAM is recommended for this step to run smoothly.
- Use pytest to run the Python unittests in your virtual environment
Check if linting also works correctly by running:
Note that we do not actually use the pre-commit tool. We use the Makefile to conveniently run the following formatting and linting tools:
If this all runs correctly, you're ready to start contributing to the Polars codebase!
Working on your issue
Create a new git branch from the
main branch in your local repository, and start coding!
The Rust code is located in the
crates directory, while the Python codebase is located in the
Both directories contain a
Makefile with helpful commands. Most notably:
make testto run the test suite (see the test suite docs for more info)
make pre-committo run autoformatting and linting
Note that your work cannot be merged if these checks fail!
make help to get a list of other helpful commands.
Two other things to keep in mind:
- If you add code that should be tested, add tests.
- If you change the public API, update the documentation.
When you have resolved your issue, open a pull request in the Polars repository. Please adhere to the following guidelines:
- Start your pull request title with a conventional commit tag. This helps us add your contribution to the right section of the changelog. We use the Angular convention. Scope can be
python, depending on your contribution.
- Use a descriptive title starting with an uppercase letter. This text will end up in the changelog.
- In the pull request description, link to the issue you were working on.
- Add any relevant information to the description that you think may help the maintainers review your code.
- Make sure your branch is rebased against the latest version of the
- Make sure all GitHub Actions checks pass.
After you have opened your pull request, a maintainer will review it and possibly leave some comments. Once all issues are resolved, the maintainer will merge your pull request, and your work will be part of the next Polars release!
Keep in mind that your work does not have to be perfect right away! If you are stuck or unsure about your solution, feel free to open a draft pull request and ask for help.
Contributing to documentation
The user guide is maintained in the
docs/user-guide folder. Before creating a PR first raise an issue to discuss what you feel is missing or could be improved.
Building and serving the user guide
The user guide is built using MkDocs. You install the dependencies for building the user guide by running
make build in the root of the repo.
Activate the virtual environment and run
mkdocs serve to build and serve the user guide, so you can view it locally and see updates as you make changes.
Creating a new user guide page
Each user guide page is based on a
.md markdown file. This file must be listed in
Adding a shell code block
To add a code block with code to be run in a shell with tabs for Python and Rust, use the following format:
=== ":fontawesome-brands-python: Python"
$ pip install fsspec
=== ":fontawesome-brands-rust: Rust"
$ cargo add aws_sdk_s3
Adding a code block
The snippets for Python and Rust code blocks are in the
docs/src/rust/ directories, respectively. To add a code snippet with Python or Rust code to a
.md page, use the following format:
- The first argument is a path to either or both files called
- The second argument is the name given at the start and end of each snippet in the
- The third argument is a list of links to functions in the API docs. For each element of the list there must be a corresponding entry in
If the corresponding
.rs snippet files both exist then each snippet named in the second argument to
code_block above must exist or the build will fail. An empty snippet should be added to the
.rs file if the snippet is not needed.
Each snippet is formatted as follows:
# --8<-- [start:read_parquet]
import polars as pl
df = pl.read_parquet("file.parquet")
# --8<-- [end:read_parquet]
The snippet is delimited by
--8<-- [start:<snippet_name>] and
--8<-- [end:<snippet_name>]. The snippet name must match the name given in the second argument to
Before committing, install
dprint (see above) and run
dprint fmt from the
docs directory to lint the markdown files.
Rust Polars uses
cargo doc to build its documentation. Contributions to improve or clarify the API reference are welcome.
For the Python API reference, we always welcome good docstring examples. There are still parts of the API that do not have any code examples. This is a great way to start contributing to Polars!
Note that we follow the numpydoc convention.
Docstring examples should also follow the Black codestyle.
py-polars directory, run
make fmt to make sure your additions pass the linter, and run
make doctest to make sure your docstring examples are valid.
Polars uses Sphinx to build the API reference.
This means docstrings in general should follow the reST format.
If you want to build the API reference locally, go to the
py-polars/docs directory and run
The resulting HTML files will be in
New additions to the API should be added manually to the API reference by adding an entry to the correct
.rst file in the
We use StackOverflow to create a database of high quality questions and answers that is searchable and remains up-to-date. There is a separate tag for each language:
Contributions in the form of well-formulated questions or answers are always welcome! If you add a new question, please notify us by adding a matching issue to our GitHub issue tracker.
This section is intended for Polars maintainers.
The steps for releasing a new Rust or Python version are similar. The release process is mostly automated through GitHub Actions, but some manual steps are required. Follow the steps below to release a new version.
Start by bumping the version number in the source code:
- Check the releases page on GitHub and find the appropriate draft release. Note the version number associated with this release.
- Make sure your fork is up-to-date with the latest version of the main Polars repository, and create a new branch.
Bump the version number.
Rust: Update the version number in all
Cargo.tomlfiles in the
polarsdirectory and subdirectories. You'll probably want to use some search/replace strategy, as there are quite a few crates that need to be updated.
Python: Update the version number in
py-polars/Cargo.tomlto match the version of the draft release.
make buildto generate a new
- Create a new commit with all files added. The name of the commit should follow the format
release(<language>): <Language> Polars <version-number>. For example:
release(python): Python Polars 0.16.1
- Push your branch and open a new pull request to the
mainbranch of the main Polars repository.
- Wait for the GitHub Actions checks to pass, then squash and merge your pull request.
Directly after merging your pull request, release the new version:
- Go to the release workflow (Python/Rust), click Run workflow in the top right, and click the green button. This will trigger the workflow, which will build all release artifacts and publish them.
- Wait for the workflow to finish, then check crates.io/PyPI/GitHub to verify that the new Polars release is now available.
It may happen that one or multiple release jobs fail. If so, you should first try to simply re-run the failed jobs from the GitHub Actions UI.
If that doesn't help, you will have to figure out what's wrong and commit a fix. Once your fix has made it to the
main branch, simply re-trigger the release workflow.
Any contributions you make to this project will fall under the MIT License that covers the Polars project.