Installing and Configuring SnowSQL

This topic describes how to download SnowSQL, install it on all supported platforms, and configure it using connection parameters, user options, and variables.

In this Topic:

Downloading the SnowSQL Installer

The SnowSQL installer is provided as a file that can be downloaded from the Snowflake web interface or as an artifact distributed through Amazon S3.

In addition, Snowflake is distributed as a package that can be installed through Homebrew Cask for Mac OS users.


Downloading and installing SnowSQL is only required for major and minor versions. For patch versions (and builds), SnowSQL upgrades automatically by default. For more information, see What is Auto-upgrade?

Web Interface

To download the SnowSQL installer from the web interface:

  1. In the Snowflake web interface, click Help > Download... to display the Downloads dialog.

  2. Select CLI Client (snowsql) on the left, then click the download icon on the right for the installer that matches your client platform:

    Snowflake SnowSQL options in Downloads dialog

Amazon S3

You can download the SnowSQL installer directly from the S3 artifact repository. No authentication is required. To determine the latest SnowSQL version that is available, see Client Changes by Version.

Run curl (or an equivalent command line tool) to download the installer. The curl syntax is as follows:

$ curl -o snowsql-<version>-<os>.[bash|pkg|msi]<bootstrap_version>/<os>/snowsql-<version>-<os>.[bash|pkg|msi]


The combined SnowSQL major and minor versions. For example, for version 1.2.3, the major version is 1 and the minor version is 2, so the bootstrap version is 1.2.
The combined SnowSQL major, minor, and patch versions. For example, for version 1.2.3, the major version is 1, the minor version is 2, and the patch version is 3. So, the version is 1.2.3.

For more information about SnowSQL versions, see Understanding SnowSQL Versioning.


The S3 URL pattern for Linux is as follows:<bootstrap_version>/linux_x86_64/snowsql-<version>-linux_x86_64.bash

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-linux_x86_64.pkg

To optionally verify the signature for the downloaded package:

  1. Download and import the latest Snowflake GPG public key from the Snowflake web interface or the public keyserver. To download from the keyserver:

    $ gpg --keyserver hkp:// --recv-keys 69BE019A
  2. Download the GPG signature along with the bash installer and verify the signature:

    $ curl -o snowsql-1.1.22-linux_x86_64.bash
    $ curl -o snowsql-1.1.22-linux_x86_64.bash.sig
    $ gpg --verify snowsql-1.1.22-linux_x86_64.bash.sig snowsql-1.1.22-linux_x86_64.bash
    gpg: Signature made Wed 22 Feb 2017 04:31:58 PM UTC using RSA key ID 69BE019A
    gpg: Good signature from "Snowflake Computing <>"
  3. Your local environment can contain multiple GPG keys; however, for security reasons, Snowflake periodically rotates the public GPG key. As a best practice, we recommend deleting the existing public key after confirming that the latest key works with the latest signed package. For example:

    $ gpg --delete-key "Snowflake Computing"

Mac OS

The S3 URL pattern for Mac OS is as follows:<bootstrap_version>/darwin_x86_64/snowsql-<version>-darwin_x86_64.pkg

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-darwin_x86_64.pkg

The Mac OS operating system can verify the installer signature automatically, so GPG signature verification is not needed.


The S3 URL pattern for Windows is as follows:<bootstrap_version>/windows_x86_64/snowsql-<version>-windows_x86_64.msi

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-windows_x86_64.msi

The Windows operating system can verify the installer signature automatically, so GPG signature verification is not needed.

Installing SnowSQL Using the Installer


  1. Open a terminal window.

  2. Run the Bash script installer:

    $ bash snowsql-linux_x86_64.bash
  3. Follow the instructions provided by the installer.

  4. Open a new terminal window to run snowsql.


The installation can be automated by setting the following environment variables:

  • SNOWSQL_DEST: Target directory of the snowsql executable.
  • SNOWSQL_LOGIN_SHELL: The login shell initialization file, which includes the PATH environment update.
$ SNOWSQL_DEST=~/bin SNOWSQL_LOGIN_SHELL=~/.profile bash snowsql-linux_x86_64.bash

Mac OS

  1. Run the PKG file by double-clicking snowsql-darwin_x86_64.pkg.
  2. Follow the instructions provided by the installer.
  3. Open a new terminal window or double-click the SnowSQL application icon to run snowsql.


Double-clicking the SnowSQL application icon starts snowsql in the current Terminal window, if one exists, or opens a new window to start the application. If you cannot see the window running snowsql, ensure the window is not minimized, hidden, or located on a second monitor.

Also, the installation can be automated by running the installer from the command line. The target directory can be set to either CurrentUserHomeDirectory (/Applications directory) or LocalSystem (~/Applications directory):

$ installer -pkg snowsql-darwin_x86_64.pkg -target CurrentUserHomeDirectory


  1. Run the MSI file by double-clicking snowsql-windows_x86_64.msi.
  2. Follow the instructions provided by the installer.
  3. Open a new terminal window to run snowsql.


The installation can be automated by running the MSI installer msiexec from the command line. The target directory cannot be changed from %ProgramFiles%\Snowflake SnowSQL. For example:

C:\Users\snowflake> msiexec /i snowsql-windows_x86_64.msi /q

Installing SnowSQL Using Homebrew Cask (Mac OS)

Homewbrew Cask is a popular extension of Homebrew used for package distribution, installation, and maintenance. There is no separate SnowSQL installer to download. If Homebrew Cask is installed on your workstation, you can install Snowflake directly.

Run the brew cask command:

$ brew cask install snowflake-snowsql

Understanding SnowSQL Versioning

SnowSQL version numbers consist of three or four digits: <major version>.<minor version>.<patch version>.<build number>.

For example, version indicates the major version is 1, the minor version is 2, the patch version is 3, and the build number is 45678.

To determine the SnowSQL version that currently starts when you run the client, use the -v option without a value:

$ snowsql -v


In general, the following guidelines apply to the different version types:

Major version:A change in the major version indicates dramatic improvements in the underlying Snowflake service. A new major version breaks backward compatibility. You will need to download and install the latest SnowSQL version from the web interface.
Minor version:A change in the minor version indicates improvements to support forward compatibility in either SnowSQL or the underlying Snowflake service. A new minor version does not break backward compatibility, but we strongly recommend that you download and install the latest SnowSQL version from the web interface.
Patch version:A change in the patch version indicates small enhancements or bug fixes were applied. The auto-upgrade feature automatically installs all patch versions.
Build number:A change in the build number indicates SnowSQL was newly built. The auto-upgrade feature automatically installs all new builds.


If a minor version is released, the functionality in your current version should continue to work, but any newly-released bug fixes and features will not be available via the auto-upgrade feature. Therefore, we strongly recommended that you download and install the latest SnowSQL version if the minor version is increased.

What is Auto-upgrade?

By default, SnowSQL upgrades itself automatically to the latest patch version or build. (A new major or minor version requires a manual download and installation.) When a newer patch version or build is available, SnowSQL downloads the new binary in a background process and executes the current version. The next time you run SnowSQL, the new version starts.

To illustrate the process:

  1. For a fresh installation, you download the SnowSQL installer (e.g., version using the Snowflake web interface and install the client.
  2. Each time you run SnowSQL, the client checks whether a newer version is available in the SnowSQL upgrade repository.
  3. If a newer version (e.g., version is available, SnowSQL downloads it as a background process while the current installed version.
  4. The next time you run SnowSQL, the client executes version while checking if a newer version is available.

Disabling Auto-upgrade

The --noup option prevents SnowSQL from downloading a new version, if available. You can specify this option while logging into Snowflake to prevent an auto-upgrade during that specific session. For example:

$ snowsql --noup

Alternatively, add the noup = true option to the configuration file to prevent SnowSQL from auto-upgrading until the option is removed or set to false.

Running a Previous SnowSQL Version

If you encounter an issue with the latest SnowSQL version, e.g., version, you can temporarily run a previous version.

To determine the SnowSQL version that currently starts when you run the client, use the -v option without a value:

$ snowsql -v


To display a list of available SnowSQL versions, use the --versions option:

$ snowsql --versions

To install an earlier SnowSQL version from the list, use the -v option and specify the version you want to install. For example, to install version

$ snowsql -v

  Installing version:  [####################################]  100%

Use the same option to specify the version you want to run when you start SnowSQL:

$ snowsql -v

Configuring SnowSQL

Configure SnowSQL by modifying the config configuration file. The file supports the following categories of settings:

The default location of the file is:

Linux/Mac OS:~/.snowsql/

You can change the default location by including the --config <path> connection parameter when starting SnowSQL.

Connection Parameters

Optionally set the default connection parameters in the [connections] section, e.g. your account name, username, and the default database and warehouse. This section also supports the ability to define named connections with different connection parameters.

Default Connection

We recommend configuring default connection parameters to simplify your connection process. Configure the default connection parameters by removing the comment symbol from any of the following parameters:

#accountname = <string>   # Account name to connect to Snowflake.
#username = <string>      # User name in the account. Optional.
#password = <string>      # User password. Optional.
#dbname = <string>        # Default database. Optional.
#schemaname = <string>    # Default schema. Optional.
#warehousename = <string> # Default warehouse. Optional.
#rolename = <string>      # Default role. Optional.
#proxy_host = <string>    # Proxy server hostname. Optional.
#proxy_port = <string>    # Proxy server port. Optional.


  • The password is stored in plain text so you must explicitly secure the config file to restrict access. For example, in Linux or Mac OS, you can set the read permissions to you alone by running chmod:

    $ chmod 700 ~/.snowsql/config
  • If your password includes special characters, enclose the password in either single quotes or double quotes.

Named Connections

If you want the ability to make multiple simultaneous connections to Snowflake, or if you simply want to store different sets of connection configurations, you can add named connections. In the configuration file, add a separate [connections] section with a unique name. Specify the connection parameters for the named connection.

For example:

accountname = abc123
username = jsmith
password = xxxxxxxxxxxxxxxxxxxx
dbname = mydb
schemaname = public
warehousename = mywh

For information on connecting to Snowflake using a named connection, see Connecting Using a Named Connection.

Configuration Options

Configure the behavior of SnowSQL by adding settings in the [options] section of the configuration file:

<option_name> = <option_value>


  • option_name is the name of the option (case-insensitive). If an invalid name is specified, SnowSQL displays an error.
  • option_value specifies a supported value (case-insensitive) for the option, as described below.
| Name                      | Value              | Help                                                                          |
| auto_completion           | True               | Displays auto-completion suggestions for commands and Snowflake objects       |
| echo                      | False              | Outputs the SQL command to the terminal when it is executed                   |
| editor                    | vim                | Changes the editor to use for the !edit command                               |
| execution_only            | False              | Executes queries only                                                         |
| exit_on_error             | False              | Quits when SnowSQL encounters an error                                        |
| friendly                  | True               | Hides the splash text and goodbye message                                     |
| header                    | True               | Outputs the header in query results                                           |
| insecure_mode             | False              | Turns off OSCP certificate checks                                             |
| key_bindings              | emacs              | Changes keybindings for navigating the prompt to emacs or vi                  |
| log_bootstrap_file        | ~/.snowsql/log_..  | SnowSQL bootstrap log file location                                           |
| log_file                  | ~/.snowsql/log     | SnowSQL main log file location                                                |
| log_level                 | CRITICAL           | Changes the log level (critical, debug, info, error, warning)                 |
| noup                      | False              | Turns off auto upgrading Snowsql                                              |
| output_file               | None               | Writes output to the specified file in addition to the terminal               |
| output_format             | psql               | Sets the output format for query results.                                     |
| prompt_format             | [user]#[warehou..  | Sets the prompt format. For help, see the documention                         |
| sfqid_in_error            | False              | Turns on/off Snowflake query id in the error message                          |
| quiet                     | False              | Hides all output                                                              |
| remove_comments           | False              | Removes comments before sending query to Snowflake                            |
| remove_trailing_semicolons | True              | Removes trailing semicolons from SQL text before sending queries to Snowflake |
| results                   | True               | If set to off, queries will be sent, but no results will be fetched.          |
| rowset_size               | 1000               | Sets the size of rowsets to fetch from the server.                            |
|                           |                    | Set the option low for smooth output, high for fast output.                   |
| stop_on_error             | False              | Stops all queries yet to run when SnowSQL encounters an error                 |
| syntax_style              | default            | Sets the colors for the text of SnowSQL.                                      |
| timing                    | True               | Turns on/off timing for each query                                            |
| variable_substitution     | False              | Substitutes variables (starting with '&') with values                         |
| wrap                      | True               | Truncates lines at the width of the terminal screen                           |

See SnowSQL Options Reference for descriptions of all valid options.


When connected to Snowflake, you can also set options using the !set command. For more information, see Commands Reference.


Configure SnowSQL variables by adding them in the [variables] section of the configuration file:

<variable_name> = <variable_value>


  • variable_name is a string of alphanumeric characters (case-insensitive) representing the name of the variable.
  • variable_value is a string representing the value for the variable. If needed, the string can be enclosed by single or double quotes.


While connected to Snowflake, you can also set variables using the !define command. For more information, see Commands Reference.

For information on using variables, see Using Variables.

SnowSQL Options Reference

Options modify the default SnowSQL behavior. You can set options in the configuration file, or using the !set command while connected to Snowflake.

The following options are supported by SnowSQL:


The option names and values are case-insensitive.


Description:Enables context-sensitive auto-completion. If enabled, functions, table names, and variables stored in SnowSQL are auto-completed in interactive mode.


Description:Echoes local input. When set to True, echoes to both stdout and the output file.


Type:String (constant)
Description:Specifies the editor to invoke for the !edit command in SnowSQL. Supported values:
  • emacs
  • vi
  • vim


Description:If enabled, SnowSQL executes queries without fetching data. This option is useful when you only want to measure execution times. Note that returned values include any network latency and are not pure server-side execution times.


Description:If enabled, SnowSQL exits when an error occurs. This behavior is useful to stop running queries when an error is encountered.


Description:If disabled, SnowSQL suppresses the startup and exit messages.


Description:Skips the certificate revocation checks using the Online Certificate Status Protocol (OCSP). This option could be used in an emergency situation in which no OCSP service is accessible. Snowflake strongly recommends that you do not enable this option unless directed by Snowflake Support.



String (constant)


Key bindings to use. Possible values:

  • emacs — when Emacs mode is enabled, [CTRL]-a is home, [CTRL]-e is end. All Emacs key bindings for the REPL environment are available.
  • vi — when vi mode is enabled, you can use all modal editing features offered by vi in the REPL environment.



Type:String (path)
Description:log_file location.



String (constant)


Default log level. Possible values:

  • INFO



Description:Prevents SnowSQL from downloading and installing a new version if True. By default, SnowSQL auto-upgrades to the latest version if no version is specified.


Type:String (path and file name)
Description:Writes output to the specified file in addition to the terminal output.



String (constant)


Specifies the format of the output displayed in the terminal. Possible values:

  • csv
  • fancy_grid
  • grid
  • html
  • latex
  • latex_booktabs
  • mediawiki
  • orgtbl
  • pipe,
  • plain
  • psql
  • rst
  • simple
  • tsv
  • custom

Recommended values: psql, fancy_grid, or grid




Description:Includes the Snowflake query ID in error messages.


Description:Removes all output data from the terminal, but continues to display error messages and diagnostic data.


Description:Removes comments from the output.


Description:Removes trailing semicolons from SQL text before sending queries to Snowflake. Note that removing the semicolons can prevent Snowflake from using cached results from different clients when the USE_CACHED_RESULT parameter is enabled.


Description:Returns the query results. If False, no query result is returned except for the execution status.


Description:Number of rows to fetch at once in interactive mode. Results are then fetched for output one rowset at a time.


Description:Stops query execution but does not exit when an error is encountered.


Description:Sets the text colors for SnowSQL. Currently, the only supported value is default.


Description:Timing of SQL statements and table rendering.


Description:Substitutes variables with the values.


Description:Wraps the output by the terminal width. If False, the outputs are truncated.