#  Installing kdb+


_You can run kdb+ on Linux, macOS, or Windows._

> **Tip — Get KDB-X Community Edition**
>
>
> You can get a free, non time-limited license for the next evolution of kdb+ with KDB-X Community Edition. For more information and to get started right away, see [Get KDB-X Community Edition](https://developer.kx.com/products/kdb-x/install).
>
##  Step 1: Download

Commercial versions of kdb+ are available to customers from the [KX Downloads Portal](https://portal.dl.kx.com/assets/raw/kdb+/). Credentials are available from the customer's [Designated Contacts](licensing.md#obtain-a-license-key-file).

Requires a 64-bit interpreter and a `k4.lic` or `kc.lic` license-key file.

> **Tip — Internal distribution at customer sites**
>
>
> Most customers download the latest release of kdb+ (along with the accompanying `README.txt`, the detailed change list) and make a limited number of approved kdb+ versions available from a central file server.
>
> Designated Contacts should encourage developers to keep production systems up to date with these versions of kdb+. This can greatly simplify development, deployment and debugging.
>
>
> **Info — Platforms and versions**
>
>
> The names of the ZIPs denote the platform: `l64.zip` – 64-bit Linux; `w64.zip` – 64-bit Windows, etc. m64 contains a universal binary suitable for both Intel and Apple Silicon Macs. l64 contains the Linux x86 build, with l64arm containing the Linux build suitable for ARM processors.
>
> Numerical release versions of the form 3.5, or 4.0 are production code. Versions of kdb+ with a trailing `t` in the name such as `3.7t` are test versions and are neither intended nor supported for production use.
>

[More about licensing](licensing.md)


##  Step 2: Unzip your download

Here we assume you install kdb+ in your `HOME` directory on Linux or macOS; or in `C:\` on Windows, and set the environment variable `QHOME` accordingly.
```txt
os        QHOME
---------------
Linux     ~/q
macOS     ~/q
Windows   c:\q
```

> **Important — You can install kdb+ anywhere as long as you set the path in `QHOME`.**
>
>
Open a command shell and `cd` to your downloads directory.

Unzip the downloaded ZIP to produce a folder `q` in your install location.

=== " Linux"
    ```bash
    unzip l64.zip -d $HOME/q
    ```

=== " macOS"
    ```bash
    unzip m64.zip -d $HOME/q
    ```

=== " Windows (PowerShell)"
    ```powershell
    Expand-Archive w64.zip -DestinationPath C:\q
    ```


##  Step 3: Install the license file

If you have a license file, `k4.lic` or `kc.lic`, put it in the `QHOME` directory.

Your `QHOME` directory will then contain:

=== "Linux"
    ```treeview
    ├── kc.lic
    ├── l64/
    │   └── q
    └── q.k
    ```

=== "macOS"
    ```treeview
    ├── kc.lic
    ├── m64/
    │   └── q
    └── q.k
    ```

=== "Windows"
    ```treeview
    ├── kc.lic
    ├── w64/
    │   └── q
    └── q.k
    ```

kdb+ looks for a license file in `QHOME`. To keep your license file elsewhere, set its path in environment variable `QLIC`.


##  Step 4: Confirm success

Confirm kdb+ is working: launch your first q session.

=== " Linux"
    ```bash
    cd
    q/l64/q
    ```

=== " macOS"
    ```bash
    cd
    spctl --add q/m64/q
    xattr -d com.apple.quarantine q/m64/q
    q/m64/q
    ```

> **Warning —  Authorizing macOS to run kdb+**
>
>
> MacOS Catalina (10.15) introduced tighter security.
> It may display a warning that it does not recognize the software.
>
> ![Catalina warning](../img/catalina-warning.png)
>
> If the `spctl` and `xattr` commands above have not authorized the OS to run q, open _System Preferences > Security & Privacy_.
>
> You should see a notification that q has been blocked – and a button to override the block.
>
> 
> [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491)
>
>
=== " Windows"
    ```powershell
    c:\q\w64\q
    ```

The q session opens with a banner like this.
```q
KDB+ 4.0 2020.06.01 Copyright (C) 1993-2020 Kx Systems
m64/ 12()core 65536MB sjt mackenzie.local 127.0.0.1 EXPIRE…

q)
```


[License errors](../basics/errors.md#license-errors),
[Licensing](licensing.md)

Try your first expression.
```q
q)til 6
0 1 2 3 4 5
```

End the q session and return to the command shell.
```q
q)\\
$
```


##  Step 5: Edit your profile

Defining `q` as a command allows you to invoke kdb+ without specifying the path to it.

The q interpreter refers to environment variable `QHOME` for the location of certain files.
Without this variable, it will guess based on the path to the interpreter.
Better to set the variable explicitly.

The `QLIC` environment variable tells kdb+ where to find [a license key file](licensing.md). Absent the variable, `QHOME` is used.

=== " Linux"

    1.  Open `~/.bash_profile` in a text editor, append the following line, and save the file. (Edit `~/.bashrc` to define a q command for non-console processes.)
    1.   `export QHOME=~/q`  
         `export PATH=~/q/l64/:$PATH`
    1.   In the command shell, use the revised profile: `source .bash_profile`

=== " macOS"

    1.  Open `~/.zshrc` in a text editor, append the following lines, and save the file. 
    1.   `export QHOME=~/q`  
         `export PATH=~/q/m64/:$PATH`
    1.   In the command shell, use the revised profile: `source ~/.zshrc`

=== " Windows"

    In the command shell issue the following commands:

    1.  `setx QHOME "C:\q"`
    1.  `setx PATH "%PATH%;C:\q\w64"`

Test the new command. Open a new command shell and type `q`.
```q
Last login: Sat Jun 20 12:42:49 on ttys004
❯ q
KDB+ 4.0 2020.06.01 Copyright (C) 1993-2020 Kx Systems
m64/ 12()core 65536MB sjt mackenzie.local 127.0.0.1 EXPIRE…

q)
```

## Further customization

### rlwrap for Linux and macOS

On Linux and macOS, the `rlwrap` command allows the Up arrow to retrieve earlier expressions in the q session. This can be very useful and it is recommended you install it.

Run `rlwrap -v` to check if it's currently installed. If not, install `rlwrap` using your [package manager](https://en.wikipedia.org/wiki/Package_manager "Wikipedia"). Common package managers are: `apt`, `dnf` and `yum` for Linux, and [Homebrew](https://brew.sh/) and [MacPorts](https://www.macports.org/) for macOS.

After installation, the q command can be changed to always run with `rlwrap`:
```bash
alias q="rlwrap -r q"
```
This can be added to the end of the user's [profile](#step-5-edit-your-profile) to take effect on every session.


[Unwrapping rlwrap](https://kx.com/blog/unwrapping-rlwrap/)


###  Interactive development environments

If you are a solo student, we recommend learning q by running it from a command shell, as a REPL, writing scripts in a text editor.
The examples on this site are produced that way; visual fidelity should help you as you learn.

[Jupyter notebooks](https://jupyter.org/) are an interactive publishing format.
We are producing lessons in this form and the library  is growing.
The [JupyterQ interface](https://github.com/KxSystems/jupyterq) lets you run q code in notebooks.

Notebooks are not, however, an IDE, and are unsuitable for studying features such as event handlers.

For more advanced study, use either the bare q REPL, or download and install our interactive development environment, [KX Developer](/developer/).

### Multiple versions

Multiple versions of kdb+ can be installed on a system by following this [guide](../kb/versions.md).

##  What’s next?

[Learn the q programming language](index.md), look through the [reference card](../ref/index.md), or see in the [Database](../database/index.md) what you can do with kdb+.