> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up

> Follow the steps in this article to install the Cognite Toolkit and the basic file structure on your computer and prepare the configuration for integration with version control repository.

We highly recommend that you use Git and a service like GitHub or Azure DevOps to manage the project configurations "as code". For governance of production projects, we also recommend using a **CI/CD pipeline** to deploy changes to Cognite Data Fusion.

## Prerequisites

* A recent version of [Python](https://www.python.org), at minimum v3.10.
* Recommended: a virtual environment manager like [Poetry](https://python-poetry.org) or [pyenv](https://github.com/pyenv/pyenv) for Python versions and dependencies.
* Recommended: Basic knowledge of Git.

<Steps>
  <Step title="Create a working root directory">
    To create the working directory, in a terminal window, run this command specifying the directory name:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    mkdir <your-working-root-directory>
    ```
  </Step>

  <Step title="Install the Cognite Toolkit from PyPi">
    The Cognite Toolkit is available as a [Python package](https://pypi.org/project/cognite-toolkit) and can be installed with *pip* or *Poetry*, ideally by using a virtual environment.

    <Tabs>
      <Tab title="pip">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        cd <your-working-root-directory>

        pyenv shell 3.11 # optional, but recommended
        pip install cognite-toolkit
        cdf --version
        ```
      </Tab>

      <Tab title="poetry">
        ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        cd <your-working-root-directory>

        poetry init . # please follow the interactive setup.
        poetry add cognite-toolkit
        poetry run cdf --version
        ```

        This will add a pyproject.toml file to that can be checked in to Git to track dependencies.
      </Tab>
    </Tabs>

    If you're using a virtual Python environment manager, and you get a `"command not found"` message in the terminal window, make sure you have activated the virtual environment, for example by using `source .venv/bin/activate` or [Poetry](https://python-poetry.org).

    <Note>
      If the installation fails, see the [troubleshooting section](#troubleshooting).
    </Note>
  </Step>

  <Step title="Initialize the configuration files and modules">
    The Cognite Toolkit manages Cognite Data Fusion projects within an organization. You can find your organization name in the browser address when you sign in to CDF: `https://<organization>.fusion.cognite.com`.

    To initialize the configuration files and modules, run this command:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf modules init <organization_dir>
    ```

    This starts the interactive setup process to create the *organization\_dir* directory and populate it with a set of configuration files and template modules to [**configure**](/cdf/deploy/cdf_toolkit/guides/usage) for your CDF projects.

    For each organization the most common setup is to have one project per environment. In this example, the organization is called "acme" and the environments are "dev" and "prod":

    ```shell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    my-working-root-directory/
      .env
      .gitignore
      README.md
      
      acme/                   # Organization directory
        config.dev.yaml       # Dev environment config
        config.prod.yaml      # Prod environment config
        modules/              # Toolkit modules
    ```
  </Step>

  <Step title="Convert the working directory to a Git repository">
    To prepare for version control and collaboration, convert the working directory into a Git repository:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}

    git init .
    cdf repo init

    ```

    The directory can now be version-controlled and is ready for further configuration. The `cdf repo init` command adds a `.gitignore` file and a `README.md` file to the repository. Use the README file to document the purpose of the repository and the configuration files.
  </Step>

  <Step title="Set up authentication and authorization">
    See the [authentication and authorization](/cdf/deploy/cdf_toolkit/guides/auth) article.
  </Step>
</Steps>

## Troubleshooting

In Windows environments, you might get this error: `ERROR: Could not install package due to an OSError: [Errno 2] No such file or directory: ...`.

The Cognite Toolkit comes installed with built-in modules. These modules are part of a directory structure that can exceed the Windows limit of 260 characters for a file path, depending on the location where you install the toolkit.

To enable support for long paths, see the [maximum path length limitation](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd#enable-long-paths-in-windows-10-version-1607-and-later) article.