# Get started with qmamba

_This page helps you get started with the qmamba package manager in KDB-X._

This quickstart takes you through initializing qmamba, creating and activating an environment, and searching for, installing, and loading a KDB-X module. For an introduction to qmamba, see the [overview](overview.md).

## Before you start

A few concepts are used extensively in the rest of this documentation. If you haven't already done so, get familiar with them first by reading the [Concepts](https://github.com/KxSystems/qmamba/blob/main/docs/concepts.md) page.

## Setup

1. Start KDB-X and load the qmamba module:
    ```txt
    ~$ ~/qx/bin/q
    KDB-X 5.0 2026.04.01 Copyright (C) 1993-2026 Kx Systems
    l64/ 12()core 5925MB user localhost 127.0.1.1 NONEXPIRE  user@example.com COMMUNITY #0000000

    Welcome to KDB-X Community Edition!
    For Community support, please visit https://kx.com/slack
    Tutorials can be found at https://github.com/KxSystems/tutorials
    Ready to go beyond the Community Edition? Email preview@kx.com

    q)qmamba:use `kx.qmamba
    ```

2. On first use, qmamba creates the root prefix (called [base](https://github.com/KxSystems/qmamba/blob/main/docs/concepts.md#baseenvironment)) inside the KDB-X installation. It installs some basic packages into the root prefix, then tells you how to start q so that it picks these up:
    ```q
    q)qmamba:use `kx.qmamba

    This is the first time you have used qmamba, initialising.

    Creating root prefix "/home/user/qx/root"

    Installing libgcc, libstdcxx, openssl, libcurl, curl, libxml2 < 2.14 from conda-forge into root prefix "/home/user/qx/root"...
    Done

    Please exit q then start it with (set an alias):

    LD_LIBRARY_PATH=/home/user/qx/root/lib /home/user/qx/bin/q
    ```

    Doing this maximizes compatibility with other conda packages, including the KDB-X modules.

    Set up an alias for this q startup command. If you forget and load qmamba, it detects this and warns you.

## Quick tour

1. Restart q as suggested, load qmamba, and list the available environments as the example below shows. Initially, this shows only the base environment that qmamba created:
    ```txt
    ~$ LD_LIBRARY_PATH=/home/user/qx/root/lib /home/user/qx/bin/q
    KDB-X 5.0 2026.04.01 Copyright (C) 1993-2026 Kx Systems
    l64/ 12()core 5924MB user localhost 127.0.1.1 NONEXPIRE  user@example.com COMMUNITY #0000000

    Welcome to KDB-X Community Edition!
    For Community support, please visit https://kx.com/slack
    Tutorials can be found at https://github.com/KxSystems/tutorials
    Ready to go beyond the Community Edition? Email preview@kx.com

    q)qmamba:use `kx.qmamba
    q)qmamba.env.list[]
      Name  Active  Path
    ────────────────────────────────────────────────────────────────
      base  *       /home/user/qx/root
    ```

> **Note**
>
> If you have used other mamba or conda tools before, any environments created by them may also be listed.
>
2. Create an environment called `test`. qmamba creates it under the root environment:
    ```q
    q)qmamba.create "test"
    Empty environment created at prefix: /home/user/qx/root/envs/test
    q)qmamba.env.list[]
      Name  Active  Path
    ──────────────────────────────────────────────
      base  *       /home/user/qx/root
      test          /home/user/qx/root/envs/test
    ```

3. Activate the `test` environment. qmamba applies subsequent operations to this environment by default. It also sets the KDB-X [search path](../module-framework/quickstart.md#search-path) (`.Q.m.SP`) to look in this environment when loading a module.
    ```q
    q)qmamba.activate "test"
    Activated environment at prefix: /home/user/qx/root/envs/test
    q)qmamba.env.list[]
      Name  Active  Path
    ──────────────────────────────────────────────
      base          /home/user/qx/root
      test  *       /home/user/qx/root/envs/test
    q).Q.m.SP
    "/home/user/qx/root/envs/test/q/mod"
    "/home/user/qx/mod"
    ```

4. Say you are looking for a [protobuf integration](https://github.com/KxSystems/protobufkdb). All KDB-X modules use the `q-` prefix, so you can limit the results by searching for packages matching `q-*protobuf*` in the `kx` channel:
    ```q
    q)qmamba.search (`SPECS`CHANNEL`PRETTY)!(enlist "q-*protobuf*";enlist "kx";1)
    Getting repodata from channels...

         q-kx-protobuf 2.0.0 hb0f4dca_0
    ────────────────────────────────────────

     Name            q-kx-protobuf
     Version         2.0.0
     Build           hb0f4dca_0
     Size            2822 kB
     License
     Subdir          linux-64
     File Name       q-kx-protobuf-2.0.0-hb0f4dca_0.conda
     URL             https://conda.anaconda.org/kx/linux-64/q-kx-protobuf-2.0.0-hb0f4dca_0.conda
     MD5             087c83e6a36eef3c8b6532c21c4f2133
     SHA256          d4200c7015c1fafd8fd1ed9ea706ae1e261a2a910f5b53f45949412342e7037a

     Dependencies:
      - libgcc >=15
      - libprotobuf 3.*
      - libstdcxx >=15
      - libprotobuf >=3.21.12,<3.22.0a0
    ```

5. Install `q-kx-protobuf`. Since it has third-party dependencies such as `libprotobuf`, add `conda-forge` to the channel list. qmamba uses that to fetch these dependencies, with `q-kx-protobuf` coming from the `kx` channel.
    ```q
    q)qmamba.install (`SPECS`CHANNEL)!(enlist "q-kx-protobuf";("kx";"conda-forge"))
    conda-forge/noarch                                  26.8MB @   3.3MB/s  8.1s
    conda-forge/linux-64                                54.9MB @   5.1MB/s 10.7s


    Transaction

      Prefix: /home/user/qx/root/envs/test

      Updating specs:

       - q-kx-protobuf


      Package          Version  Build        Channel           Size
    ─────────────────────────────────────────────────────────────────
      Install:
    ─────────────────────────────────────────────────────────────────

      + _openmp_mutex      4.5  20_gnu       conda-forge     Cached
      + libgcc          15.2.0  he0feb66_19  conda-forge     Cached
      + libgcc-ng       15.2.0  h69a702a_19  conda-forge     Cached
      + libgomp         15.2.0  he0feb66_19  conda-forge     Cached
      + libprotobuf    3.21.12  hfc55251_2   conda-forge     Cached
      + libstdcxx       15.2.0  h934c35e_19  conda-forge     Cached
      + libstdcxx-ng    15.2.0  hdf11a46_19  conda-forge     Cached
      + libzlib          1.3.2  h25fd6f3_2   conda-forge     Cached
      + q-kx-protobuf    2.0.0  hb0f4dca_0   kx              Cached

      Summary:

      Install: 9 packages

      Total download: 0 B

    ─────────────────────────────────────────────────────────────────


    Confirm changes: [Y/n]
    Y

    Transaction starting
    Linking libzlib-1.3.2-h25fd6f3_2
    Linking libgomp-15.2.0-he0feb66_19
    Linking _openmp_mutex-4.5-20_gnu
    Linking libgcc-15.2.0-he0feb66_19
    Linking libgcc-ng-15.2.0-h69a702a_19
    Linking libstdcxx-15.2.0-h934c35e_19
    Linking libstdcxx-ng-15.2.0-hdf11a46_19
    Linking libprotobuf-3.21.12-hfc55251_2
    Linking q-kx-protobuf-2.0.0-hb0f4dca_0

    Transaction finished
    ```

6. List the packages installed in the environment, which now contains `q-kx-protobuf` and its dependencies:
    ```q
    q)qmamba.list[]
    List of packages in environment: "/home/user/qx/root/envs/test"

      Name           Version  Build        Channel
    ────────────────────────────────────────────────────
      _openmp_mutex  4.5      20_gnu       conda-forge
      libgcc         15.2.0   he0feb66_19  conda-forge
      libgcc-ng      15.2.0   h69a702a_19  conda-forge
      libgomp        15.2.0   he0feb66_19  conda-forge
      libprotobuf    3.21.12  hfc55251_2   conda-forge
      libstdcxx      15.2.0   h934c35e_19  conda-forge
      libstdcxx-ng   15.2.0   hdf11a46_19  conda-forge
      libzlib        1.3.2    h25fd6f3_2   conda-forge
      q-kx-protobuf  2.0.0    hb0f4dca_0   kx
    ```

7. Load `q-kx-protobuf` and start using it:
    ```q
    q)proto:use `kx.protobuf
    q)proto.versionStr[]
    "libprotobuf v3.21.12"
    q)result:proto.serializeArrayFromList[`ScalarExample; (1i;2.2f;"abc")]
    q)result
    "\010\001\021\232\231\231\231\231\231\001@\032\003abc"
    q)proto.parseArrayToList[`ScalarExample; result]
    1i
    2.2
    "abc"
    ```

## Next steps

Now that you have seen a demonstration of qmamba, read the [qmamba usage guide](https://github.com/KxSystems/qmamba/blob/main/docs/learning-more.md) to learn more.