Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pip cannot build the mariadb package because mariadb_config is missing

Errormariadb_config not found.

Short answer

The mariadb Python package builds against MariaDB Connector/C, and it finds the library through the mariadb_config program. The error means Connector/C is not installed, its directory is not on PATH, or the installed version is older than 3.3.1. Install the development package, check mariadb_config on its own, then run pip again.

  • Applies to MariaDB Connector/Python 1.1, MariaDB Connector/C 3.3.1 and later, Python 3.12, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the shell can find mariadb_config at all, and which Connector/C version it reports.

    which mariadb_config && mariadb_config --cc_version
  2. 2Match what you see, then jump to its fix

    1. 1which prints nothing, and nothing named mariadb_config exists on the diskMariaDB Connector/C is not installedFix
    2. 2mariadb_config exists on disk but which does not find itConnector/C is installed, but its directory is not on PATHFix
    3. 3mariadb_config is found, but --cc_version prints a number below 3.3.1The installed Connector/C is too oldFix

What does the error look like?

  • mariadb_config not found.
  • Please make sure, that MariaDB Connector/C is installed on your system.
  • error: subprocess-exited-with-error while getting requirements to build wheel

Cause 1 of 3

MariaDB Connector/C is not installed

1Check

The package builds from source against Connector/C, so the library and its headers must be present before pip runs.

dpkg -l | grep -i libmariadb

2Fix

Install the Connector/C library and development files, then run pip again.

sudo apt install libmariadb3 libmariadb-dev
pip install mariadb

3Verify

mariadb_config now prints a version, and the import works.

mariadb_config --cc_version
python3 -c "import mariadb; print(mariadb.__version__)"

Confirmed by mariadb.com

Did this fix it?

Cause 2 of 3

Connector/C is installed, but its directory is not on PATH

1Check

Search the disk for the file.

sudo find / -name "mariadb_config" 2>/dev/null

2Fix

Add the directory that holds it to PATH for the shell that runs pip, then repeat the install.

export PATH="$PATH:/usr/local/mariadb/connector-c/bin"
pip install mariadb

3Verify

which finds the program.

which mariadb_config

Confirmed by mariadb.com

Did this fix it?

Cause 3 of 3

The installed Connector/C is too old

1Check

The 1.1 release of the Python package needs Connector/C 3.3.1 or later. A distribution that ships an older one fails the build.

mariadb_config --cc_version

2Fix

Install a newer Connector/C from the MariaDB download page or from MariaDB's own package repository, then build again.

# then build again
pip install mariadb

3Verify

The import works and reports its version.

python3 -c "import mariadb; print(mariadb.__version__)"

Confirmed by mariadb.com

Did this fix it?

How do I stop it coming back?

  • Install the system libraries in the same image or provisioning script that installs Python packages.
  • Pin the connector version in requirements.txt and record the Connector/C version it needs.
  • In containers, add libmariadb-dev to the build stage only if the runtime stage copies the built wheel.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.