Skip to main content
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, at minimum v3.10.
  • Recommended: a virtual environment manager like Poetry or pyenv for Python versions and dependencies.
  • Recommended: Basic knowledge of Git.
1

Create a working root directory

To create the working directory, in a terminal window, run this command specifying the directory name:
mkdir <your-working-root-directory>
2

Install the Cognite Toolkit from PyPi

The Cognite Toolkit is available as a Python package and can be installed with pip or Poetry, ideally by using a virtual environment.
  • pip
  • poetry
cd <your-working-root-directory>

pyenv shell 3.11 # optional, but recommended
pip install cognite-toolkit
cdf --version
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.
If the installation fails, see the troubleshooting section.
3

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:
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 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”:
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
4

Convert the working directory to a Git repository

To prepare for version control and collaboration, convert the working directory into a Git repository:

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.
5

Set up authentication and authorization

See the authentication and authorization article.

​
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 article.