python-gitlab is a Python package providing access to the GitLab APIs.
It includes a client for GitLab’s v4 REST API, synchronous and asynchronous GraphQL API clients, as well as a CLI tool (gitlab) wrapping REST API endpoints.
Features
python-gitlab enables you to:
write Pythonic code to manage your GitLab resources.
pass arbitrary parameters to the GitLab API. Simply follow GitLab’s docs on what parameters are available.
use a synchronous or asynchronous client when using the GraphQL API.
access arbitrary endpoints as soon as they are available on GitLab, by using lower-level API methods.
use persistent requests sessions for authentication, proxy and certificate handling.
handle smart retries on network and server errors, with rate-limit handling.
flexible handling of paginated responses, including lazy iterators.
automatically URL-encode paths and parameters where needed.
automatically convert some complex data structures to API attribute types
merge configuration from config files, environment variables and arguments.
Installation
As of 7.0.0, python-gitlab is compatible with Python 3.10+.
Use pip to install the latest stable version of python-gitlab:
$ pip install --upgrade python-gitlabThe current development version is available on both GitHub.com and GitLab.com, and can be installed directly from the git repository:
$ pip install git+https://github.com/python-gitlab/python-gitlab.gitFrom GitLab:
$ pip install git+https://gitlab.com/python-gitlab/python-gitlab.gitUsing the docker images
python-gitlab provides Docker images in two flavors, based on the Alpine and Debian slim python base images. The default tag is alpine, but you can explicitly use the alias (see below).
The alpine image is smaller, but you may want to use the Debian-based slim tag (currently based on -slim-bullseye) if you are running into issues or need a more complete environment with a bash shell, such as in CI jobs.
The images are published on the GitLab registry, for example:
registry.gitlab.com/python-gitlab/python-gitlab:latest (latest, alpine alias)
registry.gitlab.com/python-gitlab/python-gitlab:alpine (latest alpine)
registry.gitlab.com/python-gitlab/python-gitlab:slim-bullseye (latest slim-bullseye)
registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0 (alpine alias)
registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0-alpine
registry.gitlab.com/python-gitlab/python-gitlab:v3.2.0-slim-bullseye
You can run the Docker image directly from the GitLab registry:
$ docker run -it --rm registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...For example, to get a project on GitLab.com (without authentication):
$ docker run -it --rm registry.gitlab.com/python-gitlab/python-gitlab:latest project get --id gitlab-org/gitlabYou can also mount your own config file:
$ docker run -it --rm -v /path/to/python-gitlab.cfg:/etc/python-gitlab.cfg registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...Usage inside GitLab CI
If you want to use the Docker image directly inside your GitLab CI as an image, you will need to override the entrypoint, as noted in the official GitLab documentation:
Job Name:
image:
name: registry.gitlab.com/python-gitlab/python-gitlab:latest
entrypoint: [""]
before_script:
gitlab --version
script:
gitlab <command>Building the image
To build your own image from this repository, run:
$ docker build -t python-gitlab:latest .Run your own image:
$ docker run -it --rm python-gitlab:latest <command> ...Build a Debian slim-based image:
$ docker build -t python-gitlab:latest --build-arg PYTHON_FLAVOR=slim-bullseye .Bug reports
Please report bugs and feature requests at https://github.com/python-gitlab/python-gitlab/issues.
Gitter Community Chat
We have a gitter community chat available at https://gitter.im/python-gitlab/Lobby, which you can also directly access via the Open Chat button below.
If you have a simple question, the community might be able to help already, without you opening an issue. If you regularly use python-gitlab, we also encourage you to join and participate. You might discover new ideas and use cases yourself!
Documentation
The full documentation for CLI and API is available on readthedocs.
Build the docs
We use tox to manage our environment and build the documentation:
pip install tox tox -e docs
Contributing
For guidelines for contributing to python-gitlab, refer to CONTRIBUTING.rst.
3 maintainers
Release files for python-gitlab 8.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_gitlab-8.5.0.tar.gz | 411.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_gitlab-8.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 559.7 kB
Release files / python_gitlab-8.5.0.tar.gz
| Download URL | python_gitlab-8.5.0.tar.gz |
|---|---|
| Size | 411.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
628529ec4ce1f9a7ba2c145b2cf5e4eeca3015418e504b2e6fba70171b6b1b59
|
|
BLAKE2b-256 checksum How to use checksums |
26558050293b360a29218a15892c2b936e286a69fd4f5d2cf54c7cbe19d34b47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.
Transparency logRelease files / python_gitlab-8.5.0-py3-none-any.whl
| Download URL | python_gitlab-8.5.0-py3-none-any.whl |
|---|---|
| Size | 148.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
94228973c54f09eccd30f5160eca91200adc31d6ed0c894221a3865b90f96426
|
|
BLAKE2b-256 checksum How to use checksums |
933dfb547ed2ac318132517e001b74b09d1f17d2c2c681cad1e32a8b84139867
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.
Transparency log
