Implementation:Treeverse LakeFS CreateRepository

Knowledge Sources	lakeFS lakeFS API Reference
Domains	Data_Version_Control, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for creating a new versioned data repository provided by the lakeFS REST API.

Description

The createRepository endpoint initializes a new lakeFS repository backed by a specified cloud object storage namespace. Upon successful creation, the repository is provisioned with a default branch and optionally an initial empty commit. The repository name must conform to a strict naming pattern (lowercase alphanumeric, hyphens allowed, 3-63 characters), and the storage namespace must be a valid URI for a supported storage backend (S3, GCS, Azure, or local/transient for testing).

Usage

Use this API when:

Setting up a new data version control project for the first time.
Automating repository provisioning in CI/CD pipelines or infrastructure-as-code workflows.
Creating isolated repositories for different teams, projects, or environments.
Bootstrapping repositories with sample data for demonstration or testing purposes.

Code Reference

Source Location

Repository: lakeFS
File: api/swagger.yml (lines 3460-3495)

Signature

/repositories:
  post:
    operationId: createRepository
    summary: create repository
    parameters:
      - in: query
        name: bare
        schema:
          type: boolean
          default: false
        description: If true, create repository without initial commit and branch
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RepositoryCreation"
    responses:
      201:
        description: repository
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Repository"

Import

import lakefs

# Using the lakeFS Python SDK
client = lakefs.Client(
    host="http://localhost:8000",
    username="access_key_id",
    password="secret_access_key"
)
repo = lakefs.Repository("my-repo", client=client).create(
    storage_namespace="s3://my-bucket/my-repo",
    default_branch="main"
)

I/O Contract

Inputs

Name	Type	Required	Description
name	string	Yes	Repository name. Must match pattern `^[a-z0-9][a-z0-9-]{2,62}$`.
storage_namespace	string	Yes	gs\|https?\|mem\|local\|transient)://.*$.
default_branch	string	No	Name of the default branch. Defaults to `"main"`.
sample_data	boolean	No	If true, populate repository with sample data. Defaults to `false`.
read_only	boolean	No	If true, create repository in read-only mode. Defaults to `false`.
bare (query param)	boolean	No	If true, create repository without initial commit. Defaults to `false`.

Outputs

Name	Type	Description
id	string	Unique repository identifier (same as the provided name).
storage_namespace	string	The bound object storage namespace URI.
creation_date	integer (int64)	Unix epoch timestamp of when the repository was created.
default_branch	string	Name of the default branch.
read_only	boolean	Whether the repository is in read-only mode.

Usage Examples

Create a Repository Using the Python SDK

import lakefs

client = lakefs.Client(
    host="http://localhost:8000",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

# Create a new repository backed by S3
repo = lakefs.Repository("my-data-repo", client=client).create(
    storage_namespace="s3://my-bucket/my-data-repo",
    default_branch="main"
)

print(f"Repository created: {repo.id}")
print(f"Storage namespace: {repo.properties.storage_namespace}")
print(f"Default branch: {repo.properties.default_branch}")

Create a Repository Using curl

curl -X POST http://localhost:8000/api/v1/repositories \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "name": "my-data-repo",
    "storage_namespace": "s3://my-bucket/my-data-repo",
    "default_branch": "main"
  }'

Create a Bare Repository

curl -X POST "http://localhost:8000/api/v1/repositories?bare=true" \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "name": "import-target-repo",
    "storage_namespace": "s3://my-bucket/import-target"
  }'

Related Pages

Implements Principle

Principle:Treeverse_LakeFS_Repository_Creation

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment