clearml-docs/docs/fundamentals/projects.md

title
Projects

Projects are contextual containers for tasks and models (as well as dataviews when Hyper-Datasets are enabled), providing a logical structure similar to file system folders. An often useful method is to categorize components into projects according to models or objectives. Grouping into projects helps in identifying tasks, models, and dataviews when queried.

Projects can be divided into subprojects (and sub-subprojects, etc.) just like files and subdirectories on a computer, making organization easier.

Projects contain a textual description field for noting relevant information. The WebApp supports markdown rendering of the description (see overview).

In addition, the project's default output URI can be specified. When new experiments from the project are executed, the model checkpoints (snapshots) and artifacts are stored in the default output location.

WebApp

Users can create and modify projects, and see project details in the WebApp (see WebApp Home). The project's description can be edited in the overview page. Each project's experiments, models, and dataviews, can be viewed in the project's experiments table, models table, and dataviews table.

Usage

Creating Subprojects

When initializing a task, its project needs to be specified. If the project entered does not exist, it will be created. Projects can contain subprojects, just like folders can contain sub-folders. Input into the project_name parameter a target project path. The project path should follow the project tree hierarchy, in which the project and subprojects are slash (/) delimited.

For example:

from clearml import Task

Task.init(project_name='main_project/sub_project', task_name='test')

Nesting projects works on multiple levels. For example: project_name=main_project/sub_project/sub_sub_project

Projects can also be created using the projects.create REST API call.

View All Projects in System

To view all projects in the system, use the Task class method get_projects:

project_list = Task.get_projects()

This returns a list of project sorted by last update time.

More Actions

For additional ways to work with projects, use the REST API projects resource. Some of the available actions include:

• projects.create and projects.delete - create and delete projects
• projects.get_hyper_parameters - get a list of all hyperparameter sections and names used in a project
• projects.merge_projects - merge projects into a single project

See more in the REST API reference.