6.4.5 Installing Connector/Python from a Source Distribution

Connector/Python source distributions are platform independent. Source distributions are packaged in two formats:

• Zip archive format (.zip file)

• Compressed tar archive format (.tar.gz file)

Either of the two packaging formats can be used on any platforms, but Zip archives are more commonly used on Windows systems and tar archives on Unix and Unix-like systems.

Prerequisites for Compiling Connector/Python with the C Extension

Source distributions include the C Extension that interfaces with the MySQL C client library. You can build the distribution with or without support for this extension. To build Connector/Python with support for the C Extension, the following prerequisites must be satisfied:

• Compiling tools:

  • For Linux platforms: A C/C++ compiler, such as gcc.

  • For Windows platforms: Current version of Visual Studio.

• Python development files.

• For installing the classic interface only: MySQL Server binaries (server may be installed or not installed on the system), including development files (to obtain the MySQL Server binaries, visit the MySQL download site).

• For installing the X DevAPI interface only: Protobuf C++ (version 4.25.3 or later).

Installing Connector/Python from Source Code Using pip

Note

We recommend leveraging python virtual environments to encapsulate the package installation instead of installing packages directly into the Python system environment.

To install Connector/Python from a Zip archive, download its latest version from the Connector/Python download site (see Obtaining Connector/Python) and follow the steps described below.

For installing the classic interface:

1. Unpack the Zip archive in a directory of your preference.

2. Start a terminal and change location to the folder where you unpacked the Zip archive. The unpacked folder should have a layout similar to the following:

       mysql-connector-python-x.y.z-src
       ├── CHANGES.txt
       ├── CONTRIBUTING.md
       ├── LICENSE.txt
       ├── mysql-connector-python
       │   ...
       │   ├── setup.py
       │   ...
       ├── pyproject.toml
       ├── README.rst
       ├── README.txt
       └── SECURITY.md

3. Go into the mysql-connector-python-x.y.z-src folder, and perform the installation using this command:

    pip install ./mysql-connector-python

   Warning

   DO NOT use mysql-connector-python instead of ./mysql-connector-python, as the former will install the WHEEL package from the PyPI repository, and the latter will install the local WHEEL that is compiled from the source code.

   To include the C Extension, use these steps instead to provide the path to the installation directory of MySQL Server (or to the folder where the server binaries are located) with the MYSQL_CAPI system variable before running the installation step. On Linux platforms:

    $ export MYSQL_CAPI=<path to server binaries> 
    $ pip install ./mysql-connector-python

   On Windows platforms:

    > $env:MYSQL_CAPI=<path to server binaries>
    > pip install ./mysql-connector-python

   Note

   It is not required that the server is actually installed on the system; for compiling the C-extension, the presence of libraries are sufficient

For installing X DevAPI:

1. Unpack the Zip archive in a directory of your preference.

2. Start a terminal and change location to the folder where you unpacked the Zip archive. The unpacked folder should have a layout similar to the following:

     mysql-connector-python-x.y.z-src
       ├── CHANGES.txt
       ├── CONTRIBUTING.md
       ├── LICENSE.txt
       ├── mysqlx-connector-python
       │   ...
       │   ├── setup.py
       │   ...
       ├── pyproject.toml
       ├── README.rst
       ├── README.txt
       └── SECURITY.md

3. Go into the mysql-connector-python-x.y.z-src folder, and perform the installation using this commands:

    pip install ./mysqlx-connector-python

   Warning

   DO NOT use mysqlx-connector-python instead of ./mysqlx-connector-python, as the former will install the WHEEL package from the PyPI repository, and the latter will install the local WHEEL that is compiled from the source code.

   To include the Protobuf C-Extension, use these commands instead on Linux platforms to provide the path to the folder where the protobuf binaries are located by the MYSQLXPB_PROTOBUF system variable before the installation step:

    $ export MYSQLXPB_PROTOBUF=<path to protobuf binaries>
    $ export MYSQLXPB_PROTOBUF_INCLUDE_DIR="${MYSQLXPB_PROTOBUF}/include"
    $ export MYSQLXPB_PROTOBUF_LIB_DIR="${MYSQLXPB_PROTOBUF}/lib"
    $ export MYSQLXPB_PROTOC="${MYSQLXPB_PROTOBUF}/bin/protoc"
    $ pip install ./mysqlx-connector-python

   Or these commands on Windows platforms to provide the path to the folder where the protobuf binaries are located by the PROTOBUF system variable before the installation step:

    > $env:PROTOBUF=<path to protobuf binaries>
    > $env:PROTOBUF_INCLUDE_DIR=$env:PROTOBUF+"\include"
    > $env:PROTOBUF_LIB_DIR=$env:PROTOBUF+"\lib"
    > $env:PROTOC=$env:PROTOBUF+"\bin\protoc.exe"
    > pip install ./mysqlx-connector-python

   Note

   It is not required that the server is actually installed on the system; for compiling the C-extension, the presence of libraries are sufficient