python-gitlab

8.2.0 verified Tue May 12 auth: no python install: verified

python-gitlab is a Python package that provides a comprehensive wrapper for the GitLab REST and GraphQL APIs. It allows developers to interact with GitLab resources in a Pythonic way, offering both synchronous and asynchronous clients, along with a CLI tool. The library maintains a regular release cadence, typically releasing new versions monthly, ensuring up-to-date support for GitLab API features.

pip install python-gitlab

Common errors

error ModuleNotFoundError: No module named 'gitlab' ↓

cause The `python-gitlab` library is not installed in the Python environment being used.

fix

pip install python-gitlab

error gitlab.exceptions.GitlabError: 401 Unauthorized ↓

cause This error indicates that the provided personal access token is invalid, expired, or lacks the necessary scope to perform the requested action.

fix

Verify your GitLab URL and private token, ensuring it has the necessary scopes (e.g., api) and is still active.

error gitlab.exceptions.GitlabError: 404 Not Found ↓

cause This error occurs when the requested GitLab resource (e.g., project, user, group) does not exist or the authenticated user does not have permission to access it.

fix

Double-check the ID or name of the resource you are trying to access and ensure your token has the correct permissions for visibility.

error gitlab.exceptions.GitlabError: 400 Bad Request ↓

cause This error typically indicates that an API request was malformed, missing required parameters, or contained invalid data according to the GitLab API specification for that endpoint.

fix

Review the GitLab API documentation for the specific endpoint (e.g., projects.create()) to ensure all required parameters are provided and correctly formatted.

error AttributeError: 'GitlabList' object has no attribute 'decode' ↓

cause This error occurs when attempting to call the `decode()` method on a `GitlabList` or `GitlabDict` object, which are Python objects representing API responses, not raw byte strings.

fix

Access the data directly as a Python list or dictionary, or iterate through its elements, as python-gitlab handles decoding automatically.

Warnings

breaking python-gitlab v7.0.0 and later require Python 3.10 or higher. Python 3.9 and older are no longer supported. ↓

fix Upgrade your Python environment to 3.10 or newer. Ensure your `pyproject.toml` or `requirements.txt` specifies `python_requires='>=3.10'` for compatibility.

breaking In python-gitlab v8.0.0, the GraphQL API client's `GraphQL.execute()` method no longer accepts `graphql.Source` objects directly. ↓

fix Review the GraphQL client usage and adapt to the updated `GraphQL.execute()` signature, likely by passing the query string directly or using `gql` package objects.

gotcha Password-based authentication (username/password) is deprecated and largely removed from GitLab API v10.2 onwards. It is highly recommended to use Personal Access Tokens or OAuth tokens. ↓

fix Switch to Personal Access Tokens, Project Access Tokens, or OAuth tokens for authentication. Avoid using direct username/password pairs.

gotcha If your GitLab instance redirects HTTP requests to HTTPS (e.g., `http://gitlab.example.com` to `https://gitlab.example.com`), you must specify the final HTTPS URL in the `Gitlab` object constructor to avoid `RedirectionError` or malformed requests. ↓

fix Always use the canonical (final) URL of your GitLab instance, typically starting with `https://`, when initializing the `Gitlab` object.

gotcha By default, python-gitlab handles rate limiting by sleeping and retrying based on `Retry-After` headers or exponential backoff. It also does *not* retry transient HTTP errors (5xx codes) by default. ↓

fix To customize rate limiting behavior (e.g., disable waiting), use `obey_rate_limit=False` or `max_retries`. To enable automatic retries for transient errors, set `retry_transient_errors=True` during `Gitlab` object initialization or on individual API calls.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.63s 23.2M

3.10 alpine (musl) - - 0.67s 23.1M

3.10 slim (glibc) wheel 2.3s 0.48s 24M

3.10 slim (glibc) - - 0.47s 24M

3.11 alpine (musl) wheel - 0.81s 25.5M

3.11 alpine (musl) - - 0.93s 25.4M

3.11 slim (glibc) wheel 2.3s 0.74s 26M

3.11 slim (glibc) - - 0.70s 26M

3.12 alpine (musl) wheel - 0.74s 17.2M

3.12 alpine (musl) - - 0.80s 17.1M

3.12 slim (glibc) wheel 2.1s 0.73s 18M

3.12 slim (glibc) - - 0.78s 18M

3.13 alpine (musl) wheel - 0.73s 16.9M

3.13 alpine (musl) - - 0.74s 16.7M

3.13 slim (glibc) wheel 2.1s 0.69s 17M

3.13 slim (glibc) - - 0.74s 17M

3.9 alpine (musl) wheel - 0.57s 22.4M

3.9 alpine (musl) - - 0.63s 22.4M

3.9 slim (glibc) wheel 2.7s 0.55s 23M

3.9 slim (glibc) - - 0.55s 23M

Imports

Gitlab

wrong

from gitlab import Gitlab # While technically possible, the standard and often safer practice is to import the top-level 'gitlab' module, especially to avoid conflicts or when using other submodules.

correct

import gitlab
gl = gitlab.Gitlab(...)

Importing the top-level 'gitlab' module is the standard and recommended practice for accessing the Gitlab class and other functionalities.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to connect to a GitLab instance using a personal access token and then fetch a list of projects owned by the authenticated user. It highlights setting the GitLab URL and private token via environment variables for security and explicitly uses API v4.

import os
import gitlab

# Configure GitLab connection using environment variables
GITLAB_URL = os.environ.get('GITLAB_URL', 'https://gitlab.com')
GITLAB_PRIVATE_TOKEN = os.environ.get('GITLAB_PRIVATE_TOKEN', 'your_private_token_here')

# Initialize the Gitlab API client
# Ensure you use 'https://' if your GitLab instance redirects from http
try:
    gl = gitlab.Gitlab(
        url=GITLAB_URL,
        private_token=GITLAB_PRIVATE_TOKEN,
        api_version='4' # Explicitly set API version, often '4'
    )
    
    # Optional: Validate the token by getting the current authenticated user
    gl.auth() 
    user = gl.user.get()
    print(f"Connected to GitLab as: {user.username}")

    # List current user's projects
    print("\nListing your projects:")
    projects = gl.projects.list(owned=True, all=True)
    if projects:
        for project in projects:
            print(f"  - {project.name} (ID: {project.id})")
    else:
        print("  No projects found.")

except gitlab.exceptions.GitlabError as e:
    print(f"GitLab API error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")