Skip to content

Environment Variables

This page explains how to use a .env file to set environment variables that apply to a single workspace in the kdb Visual Studio Code Extension.

A .env file in the root of a workspace folder lets you set environment variables that apply only to that workspace, without changing your operating system environment.

The extension reads the file when it starts a KX REPL and merges the variables into the environment of the q process that it launches. This is the recommended place for workspace-specific values such as QHOME, QLIC, or PYKX_USE_FIND_LIBPYTHON.

The extension reads the file every time a REPL starts, so restart the REPL after you edit it to apply your changes.

Location

The file must be named .env and be in the root of the workspace folder:

my-workspace/
├── .env
├── .vscode/
│   └── settings.json
└── main.q

In a multi-root workspace, each folder has its own .env file, and the extension uses the one that belongs to the folder the REPL started for. If a file does not belong to any workspace folder, the extension applies no .env file.

Note

The Python extension reads the same file by default (python.envFile), so the extension also picks up the variables you set here when it activates a virtual environment for the REPL.

Syntax

Use one KEY=VALUE assignment per line:

QHOME=/opt/kdb
QLIC=/opt/kdb/lic
PYKX_USE_FIND_LIBPYTHON="true"

# Lines starting with a hash are comments

The following rules apply:

  • The extension ignores blank lines and lines whose first non-whitespace character is #.
  • The extension trims the whitespace around the key and the value.
  • The extension removes quotes (" and ') from the value, so PYKX_USE_FIND_LIBPYTHON="true" and PYKX_USE_FIND_LIBPYTHON=true are equivalent.
  • The export prefix and multi-line values are not supported.
  • A value cannot contain =. The extension discards everything from the second = onwards.

Variable expansion

Values can reference other variables in either POSIX or Windows form:

QHOME=/opt/kdb
QLIC=${QHOME}/lic
QPATH=$QHOME/mod
HOSTNAME=%COMPUTERNAME%

The extension expands $NAME, ${NAME}, and %NAME%. It resolves a reference against the variables defined earlier in the same .env file first, and then against the environment that the extension itself runs in. If the extension cannot resolve a reference, it leaves the value unchanged.

Precedence

For the q process that the extension launches, the values in .env override the variables inherited from the operating system.

QHOME is the exception, because the extension also has settings for it. To locate the q executable, the extension uses the following order:

  1. kdb.qHomeDirectoryWorkspace, set in .vscode/settings.json
  2. QHOME from .env, or from the operating system if .env does not set it
  3. kdb.qHomeDirectory
  4. The default KDB-X install location $HOME/.kx, and then the system path

For more information about these settings, refer to KDB-X in VS Code and the extension settings.

The extension also adjusts QPATH for KDB-X: it prepends the module directory of the folder that the REPL runs in to whatever QPATH resolves to, so that the REPL finds the modules local to your workspace first.

Scope

The .env file applies to the REPL only, because the REPL is the process that the extension launches itself. It has no effect on the q processes that you connect to as My q connections, or on kdb Insights Enterprise connections. Those processes run outside of VS Code and take their environment from wherever they started.

Remote settings

When you work on a remote machine, your settings apply to the remote host rather than to your local machine. To edit them after the remote connection is established:

  1. Open the Command Palette and search for settings json.
  2. Select Preferences: Open Remote Settings (JSON).

Remote Settings

Next steps