Step 1: install a C compiler#

How to do this will depend on your platform.

Windows

You will needBuild Tools for Visual Studio 2022.

Alternatively, you can install the necessary components on the commandline usingvs_BuildTools.exe

Alternatively, you could use theWSLand consult theLinux instructions below.

macOS

To use theconda-based compilers, you will need to install theDeveloper Tools usingxcode-select--install.

If you prefer to use a different compiler, general information can be found here:https://devguide.python.org/setup/#macos

Linux

For Linux-basedconda installations, you won’t have to install anyadditional components outside of the conda environment. The instructionsbelow are only needed if your setup isn’t based on conda environments.

Some Linux distributions will come with a pre-installed C compiler. To find outwhich compilers (and versions) are installed on your system:

# for Debian/Ubuntu:dpkg--list|grepcompiler# for Red Hat/RHEL/CentOS/Fedora:yumlistinstalled|grep-i--colorcompiler

GCC (GNU Compiler Collection), is a widely usedcompiler, which supports C and a number of other languages. If GCC is listedas an installed compiler nothing more is required.

If no C compiler is installed, or you wish to upgrade, or you’re using a differentLinux distribution, consult your favorite search engine for compiler installation/updateinstructions.

Let us know if you have any difficulties by opening an issue or reaching out on our contributorcommunitySlack.

Step 2: create an isolated environment#

Before we begin, please:

• Make sure that you havecloned the repository

• cd to the pandas source directory you just created with the clone command

condaenvcreate--fileenvironment.ymlcondaactivatepandas-dev

# Create a virtual environment# Use an ENV_DIR of your choice. We'll use ~/virtualenvs/pandas-dev# Any parent directories should already existpython3-mvenv~/virtualenvs/pandas-dev# Activate the virtualenv.~/virtualenvs/pandas-dev/bin/activate# Install the build dependenciespython-mpipinstall-rrequirements-dev.txt

# Create a virtual environment# Use an ENV_DIR of your choice. We'll use ~/Users/<yourname>/.pyenv/versions/pandas-devpyenvvirtualenv<version><name-to-give-it># For instance:pyenvvirtualenv3.11pandas-dev# Activate the virtualenvpyenvactivatepandas-dev# Now install the build dependencies in the cloned pandas repopython-mpipinstall-rrequirements-dev.txt

# Create a virtual environmentpython-mvenv$env:USERPROFILE\virtualenvs\pandas-dev# Activate the virtualenv. Use activate.bat for cmd.exe~\virtualenvs\pandas-dev\Scripts\Activate.ps1# Install the build dependenciespython-mpipinstall-rrequirements-dev.txt

Step 3: build and install pandas#

There are currently two supported ways of building pandas, pip/meson and setuptools(setup.py).Historically, pandas has only supported using setuptools to build pandas. However, this methodrequires a lot of convoluted code in setup.py and also has many issues in compiling pandas in paralleldue to limitations in setuptools.

The newer build system, invokes the meson backend through pip (via aPEP 517 build).It automatically uses all available cores on your CPU, and also avoids the need for manual rebuilds byrebuilding automatically whenever pandas is imported (with an editable install).

For these reasons, you should compile pandas with meson.Because the meson build system is newer, you may find bugs/minor issues as it matures. You can report these bugshere.

To compile pandas with meson, run:

# Build and install pandas# By default, this will print verbose output# showing the "rebuild" taking place on import (see section below for explanation)# If you do not want to see this, omit everything after --no-build-isolationpython-mpipinstall-ve.--no-build-isolation-Ceditable-verbose=true

# set the upstream repository, if not done already, and fetch the latest tagsgitremoteaddupstreamhttps://github.com/pandas-dev/pandas.gitgitfetchupstream--tags

Build options

It is possible to pass options from the pip frontend to the meson backend if you would like to configure yourinstall. Occasionally, you’ll want to use this to adjust the build directory, and/or toggle debug/optimization levels.

You can pass a build directory to pandas by appending-Cbuilddir="yourbuilddirhere" to your pip command.This option allows you to configure where meson stores your built C extensions, and allows for fast rebuilds.

Sometimes, it might be useful to compile pandas with debugging symbols, when debugging C extensions.Appending-Csetup-args="-Ddebug=true" will do the trick.

With pip, it is possible to chain together multiple config settings. For example, specifying both a build directoryand building with debug symbols would look like-Cbuilddir="yourbuilddirhere"-Csetup-args="-Dbuildtype=debug".

Compiling pandas with setup.py

To compile pandas with setuptools, run:

pythonsetup.pydevelop

python-mpipuninstallpandas

This is because python setup.py develop will not uninstall the loader script thatmeson-pythonuses to import the extension from the build folder, which may cause errors such as anFileNotFoundError to be raised.

Checking the build

At this point you should be able to import pandas from your locally built version:

$ python>>> import pandas>>> print(pandas.__version__)  # note: the exact output may differ2.0.0.dev0+880.g2b9e661fbb.dirty

At this point you may want to tryrunning the test suite.

Keeping up to date with the latest build

When building pandas with meson, importing pandas will automatically trigger a rebuild, even when C/Cython files are modified.By default, no output will be produced by this rebuild (the import will just take longer). If you would like to see meson’soutput when importing pandas, you can set the environment variableMESONPY_EDITABLE_VERBOSE. For example, this would be:

# On Linux/macOSMESONPY_EDITABLE_VERBOSE=1python# WindowssetMESONPY_EDITABLE_VERBOSE=1# Only need to set this once per sessionpython

If you would like to see this verbose output every time, you can set theeditable-verbose config setting totrue like so:

python-mpipinstall-ve.-Ceditable-verbose=true