Installing the Python Connector

This topic provides instructions for installing the Snowflake Connector for Python. The connector can currently be installed in Linux, macOS, and Windows environments.

The developer notes are hosted on GitHub, along with the source code.

In this Topic:

Prerequisites

For a list of the operating systems supported by Snowflake clients, see Operating System Support.

The following software packages are required to install the Snowflake Connector for Python.

Python

On linux and macOS, the Snowflake Connector for Python requires Python 3.5, 3.6, 3.7, or 3.8.

On MS-Windows, the Snowflake Connector for Python requires Python 3.5, 3.6, or 3.7.

To verify your version of Python:

python --version

For more information about installing the required version of Python, see:

Python Package Installer and Setup Tools

The Snowflake Connector for Python is installed by pip, a standard Python package installer and manager.

Use pip version 19.0 or later. Execute the following command to ensure the required version is installed:

python -m pip install --upgrade pip

Note

  • On macOS, use either virtualenv or pyvenv to install Python and the connector.

  • If both Python 2.7.x and Python 3.5.x are installed, use pip3 to install the connector with Python 3.5.x.

  • If pip (or pip3) is installed in the system directory or a shared directory, use sudo to run the above command, which ensures you have the privileges required to write/copy files to the directory.

Python Packages

The Python connector uses many Python packages. Snowflake documents the version numbers of packages used in testing each release of the Python connector; the documents are at: https://github.com/snowflakedb/snowflake-connector-python/tree/master/tested_requirements.

The repository contains one file for each version of Python (e.g. 3.7) that the Python connector supports. Each file consists of lines like the following:

asn1crypto==1.3.0

The element to the left of the == is the name of the package, and the element to the right of the == is the version number of that package.

Snowflake recommends that you use the same version of the library that Snowflake used during testing. Snowflake recommends that you not override pinned dependencies, or use applications that might override pinned dependencies.

pyOpenSSL (macOS only)

macOS (Yosemite and higher versions) includes Python 2.7.x. If you are using python 2.7.x, and if your version of pyOpenSSL is out-of-date, you might encounter the following error if you are not using virtualenv:

File "/Library/Python/2.7/site-packages/snowflake/connector/ocsp_pyopenssl.py", line nn, in dump_publickey
  bio = OpenSSL.crypto._new_mem_buf()
AttributeError: 'module' object has no attribute '_new_mem_buf'

To fix this issue, use one of the following two options:

  • Use either virtualenv or pyvenv to isolate the Python runtime environments.

  • Set the PYTHONPATH environment variable so that the newly-installed pyOpenSSL is used instead. For example:

    export PYTHONPATH=/Library/Python/2.7/site-packages
    

Note

Recent and future versions of the Python connector support only Python 3.x. If you are still using Python 2.7 and an older version of the Python connector, Snowflake encourages you to upgrade both the connector and Python.

OpenSSL and FFI (Linux only)

When the Snowflake Connector for Python is installed, pip compiles native codes in the packages on Linux platforms. In order to install it successfully, install the required packages:

  • For CentOS, use yum:

    sudo yum install -y libffi-devel openssl-devel
    
  • For Ubuntu, use apt-get:

    sudo apt-get install -y libssl-dev libffi-dev
    

Other platforms do not need the OS packages installed because they are bundled in the Python packages.

Step 1: Install the Connector

You can install the Snowflake Connector for Python with or without support for the Pandas data analysis library. For instructions on installing Snowflake with support for Pandas, see Using Pandas DataFrames with the Python Connector.

To install the Python Connector without support for Pandas, continue with the instructions in this section.

The Snowflake Connector for Python is available in PyPI. A change log is available on the site, so you can determine the changes that have been implemented in each release.

To install the connector, execute the following command:

pip install --upgrade snowflake-connector-python

pip automatically installs all required modules.

Note

  • As mentioned earlier, you might need to use sudo to run pip (or pip3), which ensures you have the privileges required to write/copy files.

  • If pip returns compilation errors, you might need to install the C compiler and Python development package to build some of the required modules, such as PyCryptoDome.

    For more information about installing a C compiler, see http://gcc.gnu.org/ (Linux) or https://developer.apple.com/xcode/ (macOS).

Step 2: Verify Your Installation

Create a file (e.g. validate.py) containing the following Python sample code, which connects to Snowflake and displays the Snowflake version:

#!/usr/bin/env python
import snowflake.connector

# Gets the version
ctx = snowflake.connector.connect(
    user='<your_user_name>',
    password='<your_password>',
    account='<your_account_name>'
    )
cs = ctx.cursor()
try:
    cs.execute("SELECT current_version()")
    one_row = cs.fetchone()
    print(one_row[0])
finally:
    cs.close()
ctx.close()

Make sure to replace <your_user_name>, <your_password>, and <your_account_name> with the appropriate values for your Snowflake account.

Important

Account name is required. In addition, note that your full account name might include additional segments that identify the region and cloud platform where your account is hosted.

Account name examples by region

If your account name is xy12345:

Cloud Platform / Region

Full Account Name

AWS

US West (Oregon)

xy12345

US East (Ohio)

xy12345.us-east-2.aws

US East (N. Virginia)

xy12345.us-east-1

US East (Commercial Gov - N. Virginia)

xy12345.us-east-1-gov.aws

Canada (Central)

xy12345.ca-central-1.aws

EU (Ireland)

xy12345.eu-west-1

EU (Frankfurt)

xy12345.eu-central-1

Asia Pacific (Tokyo)

xy12345.ap-northeast-1.aws

Asia Pacific (Mumbai)

xy12345.ap-south-1.aws

Asia Pacific (Singapore)

xy12345.ap-southeast-1

Asia Pacific (Sydney)

xy12345.ap-southeast-2

GCP

US Central1 (Iowa)

xy12345.us-central1.gcp

Europe West2 (London)

xy12345.europe-west2.gcp

Europe West4 (Netherlands)

xy12345.europe-west4.gcp

Azure

West US 2 (Washington)

xy12345.west-us-2.azure

East US 2 (Virginia)

xy12345.east-us-2.azure

US Gov Virginia

xy12345.us-gov-virginia.azure

Canada Central (Toronto)

xy12345.canada-central.azure

West Europe (Netherlands)

xy12345.west-europe.azure

Switzerland North (Zurich)

xy12345.switzerland-north.azure

Southeast Asia (Singapore)

xy12345.southeast-asia.azure

Australia East (New South Wales)

xy12345.australia-east.azure

Important

If either of the following conditions is true, your account name is different than the structure described in this example:

  • If your Snowflake Edition is VPS, please contact Snowflake Support for details about your account name.

  • If AWS PrivateLink is enabled for your account, your account name requires an additional privatelink segment. For more details, see AWS PrivateLink & Snowflake.

Also, note that you do not include the Snowflake domain name (snowflakecomputing.com) as part of your account name. Snowflake automatically appends the domain name to your account name to create the required connection.

For more information about the Snowflake Python API, see Python Connector API, specifically the snowflake.connector methods for details about the supported connector parameters.

Next, execute the sample code. For example, if you created a file named validate.py:

python validate.py

The Snowflake version (e.g. 3.5.0) should be displayed.

If you see the following error message, your Python installation likely does not have the appropriate security fixes:

ERROR: The ssl package installed with your Python package - version n.n.n -
does not have the required security fixes. Upgrade to 3.5.0 or higher.

Step 3: Specify a Temporary Directory

The Snowflake Connector for Python uses a temporary directory to store data for loading and unloading (PUT, GET), as well as other types of temporary data.

The temporary directory can be explicitly specified by setting the TMPDIR, TEMP or TMP environment variables, otherwise the operating system’s default temporary directory (i.e. /tmp, C:\temp) is used.

If the system’s default temporary directory volume is not large enough for the data being processed, you should specify a different directory using any of the supported environment variables.

For example, from a terminal window, execute the following command:

export TMPDIR=/large_tmp_volume