[Skip to main content](https://docs.gitlab.com/api/project_import_export/#skipTarget) [Go to GitLab Docs homepage](https://docs.gitlab.com/)
`/`
[What's new?](https://about.gitlab.com/releases/whats-new/)
English
  * Language
  * English
  * 日本語


v18.10
  *     * [18.10 (not yet released)](https://docs.gitlab.com/api/project_import_export/)
  *     * [18.9 (recently released)](https://docs.gitlab.com/18.9/api/project_import_export/)
    * [18.8](https://docs.gitlab.com/18.8/api/project_import_export/)
    * [18.7](https://archives.docs.gitlab.com/18.7/api/project_import_export/)
  *     * [17.11](https://archives.docs.gitlab.com/17.11/api/project_import_export/)
    * [16.11](https://archives.docs.gitlab.com/16.11/ee/api/project_import_export.html)
  *     * [Archives](https://docs.gitlab.com/archives)


Select theme and layout
  * Light mode
  * Dark mode
  * Auto


  * Fixed width
  * Fluid width


[What's new?](https://about.gitlab.com/releases/whats-new/) [Get free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&amp;glm_content=navigation-cta-docs)
Toggle menu
  * [Use GitLab](https://docs.gitlab.com/user/)
  * [GitLab Duo](https://docs.gitlab.com/user/gitlab_duo/)
  * [Extend](https://docs.gitlab.com/api/)
  * [Install](https://docs.gitlab.com/install/)
  * [Administer](https://docs.gitlab.com/administration/)
  * [Subscribe](https://docs.gitlab.com/subscriptions/)
  * [Contribute](https://docs.gitlab.com/development/)
  * [Solutions](https://docs.gitlab.com/solutions/)


Select a topicUse GitLab GitLab Duo Extend Install Administer Subscribe Contribute Solutions
[Getting started](https://docs.gitlab.com/api/get_started/get_started_extending/)
[Tutorials](https://docs.gitlab.com/tutorials/develop/)
[Integrations](https://docs.gitlab.com/integration/)
[Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/)
[REST API](https://docs.gitlab.com/api/rest/)
[Resources](https://docs.gitlab.com/api/api_resources/)
[.gitignore (templates)](https://docs.gitlab.com/api/templates/gitignores/)
[.gitlab-ci.yml (templates)](https://docs.gitlab.com/api/templates/gitlab_ci_ymls/)
[Access requests](https://docs.gitlab.com/api/access_requests/)
[Agent for Kubernetes](https://docs.gitlab.com/api/cluster_agents/)
[AI Catalog admin](https://docs.gitlab.com/api/admin/ai_catalog/)
[Alert management](https://docs.gitlab.com/api/alert_management_alerts/)
[Application appearance](https://docs.gitlab.com/api/appearance/)
[Application settings](https://docs.gitlab.com/api/settings/)
[Application statistics](https://docs.gitlab.com/api/statistics/)
[Applications](https://docs.gitlab.com/api/applications/)
[Attestations](https://docs.gitlab.com/api/attestations/)
[Audit events](https://docs.gitlab.com/api/audit_events/)
[Avatar](https://docs.gitlab.com/api/avatar/)
[Branches](https://docs.gitlab.com/api/branches/)
[Broadcast messages](https://docs.gitlab.com/api/broadcast_messages/)
[Cluster discovery (certificate-based) (deprecated)](https://docs.gitlab.com/api/cluster_discovery/)
[Code Suggestions](https://docs.gitlab.com/api/code_suggestions/)
[Commits](https://docs.gitlab.com/api/commits/)
[Compliance and policy settings](https://docs.gitlab.com/api/compliance_policy_settings/)
[Composer](https://docs.gitlab.com/api/packages/composer/)
[Conan v1](https://docs.gitlab.com/api/packages/conan_v1/)
[Conan v2](https://docs.gitlab.com/api/packages/conan_v2/)
[Container registry](https://docs.gitlab.com/api/container_registry/)
[Container repository protection rules](https://docs.gitlab.com/api/container_repository_protection_rules/)
[Container registry protection tag rules](https://docs.gitlab.com/api/container_registry_protection_tag_rules/)
[Container virtual registry](https://docs.gitlab.com/api/container_virtual_registries/)
[Custom attributes](https://docs.gitlab.com/api/custom_attributes/)
[Database migrations](https://docs.gitlab.com/api/database_migrations/)
[Data management](https://docs.gitlab.com/api/admin/data_management/)
[Debian](https://docs.gitlab.com/api/packages/debian/)
[Debian group distributions](https://docs.gitlab.com/api/packages/debian_group_distributions/)
[Debian project distributions](https://docs.gitlab.com/api/packages/debian_project_distributions/)
[Dependencies](https://docs.gitlab.com/api/dependencies/)
[Dependency list export](https://docs.gitlab.com/api/dependency_list_export/)
[Dependency Proxy](https://docs.gitlab.com/api/dependency_proxy/)
[Deploy keys](https://docs.gitlab.com/api/deploy_keys/)
[Deploy tokens](https://docs.gitlab.com/api/deploy_tokens/)
[Deployments](https://docs.gitlab.com/api/deployments/)
[Discussions](https://docs.gitlab.com/api/discussions/)
[Dockerfile (templates)](https://docs.gitlab.com/api/templates/dockerfiles/)
[DORA4 metrics](https://docs.gitlab.com/api/dora/metrics/)
[Emoji reactions](https://docs.gitlab.com/api/emoji_reactions/)
[Environments](https://docs.gitlab.com/api/environments/)
[Epics (deprecated)](https://docs.gitlab.com/api/epics/)
[Error tracking](https://docs.gitlab.com/api/error_tracking/)
[Events](https://docs.gitlab.com/api/events/)
[Experiments](https://docs.gitlab.com/api/experiments/)
[External status checks](https://docs.gitlab.com/api/status_checks/)
[Feature flags](https://docs.gitlab.com/api/feature_flags/)
[Feature flag user lists](https://docs.gitlab.com/api/feature_flag_user_lists/)
[Freeze periods](https://docs.gitlab.com/api/freeze_periods/)
[Geo nodes (deprecated)](https://docs.gitlab.com/api/geo_nodes/)
[Geo sites](https://docs.gitlab.com/api/geo_sites/)
[GitLab Duo Chat completions](https://docs.gitlab.com/api/chat/)
[GitLab Pages](https://docs.gitlab.com/api/pages/)
[GLQL](https://docs.gitlab.com/api/glql/)
[Go Proxy](https://docs.gitlab.com/api/packages/go_proxy/)
[Google Cloud integration](https://docs.gitlab.com/api/google_cloud_integration/)
[Groups](https://docs.gitlab.com/api/groups/)
[Helm](https://docs.gitlab.com/api/packages/helm/)
[Import](https://docs.gitlab.com/api/import/)
[Instance CI/CD variables](https://docs.gitlab.com/api/instance_level_ci_variables/)
[Invitations](https://docs.gitlab.com/api/invitations/)
[Issues](https://docs.gitlab.com/api/issues/)
[Issues (epic) (deprecated)](https://docs.gitlab.com/api/epic_issues/)
[Issues statistics](https://docs.gitlab.com/api/issues_statistics/)
[Jobs](https://docs.gitlab.com/api/jobs/)
[Job artifacts](https://docs.gitlab.com/api/job_artifacts/)
[Job token scopes](https://docs.gitlab.com/api/project_job_token_scopes/)
[Keys](https://docs.gitlab.com/api/keys/)
[License](https://docs.gitlab.com/api/license/)
[Licenses (templates)](https://docs.gitlab.com/api/templates/licenses/)
[Linked epics (deprecated)](https://docs.gitlab.com/api/linked_epics/)
[Links (issue)](https://docs.gitlab.com/api/issue_links/)
[Links (epic) (deprecated)](https://docs.gitlab.com/api/epic_links/)
[Lint .gitlab-ci.yml](https://docs.gitlab.com/api/lint/)
[Markdown](https://docs.gitlab.com/api/markdown/)
[Maven](https://docs.gitlab.com/api/packages/maven/)
[Maven virtual registry](https://docs.gitlab.com/api/maven_virtual_registries/)
[Member roles](https://docs.gitlab.com/api/member_roles/)
[Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)
[Merge request approval settings](https://docs.gitlab.com/api/merge_request_approval_settings/)
[Merge request context commits](https://docs.gitlab.com/api/merge_request_context_commits/)
[Merge requests](https://docs.gitlab.com/api/merge_requests/)
[Merge trains](https://docs.gitlab.com/api/merge_trains/)
[Metadata](https://docs.gitlab.com/api/metadata/)
[Model registry](https://docs.gitlab.com/api/model_registry/)
[Namespaces](https://docs.gitlab.com/api/namespaces/)
[Notes (comments)](https://docs.gitlab.com/api/notes/)
[Notification settings](https://docs.gitlab.com/api/notification_settings/)
[npm](https://docs.gitlab.com/api/packages/npm/)
[NuGet](https://docs.gitlab.com/api/packages/nuget/)
[Organizations](https://docs.gitlab.com/api/organizations/)
[Packages](https://docs.gitlab.com/api/packages/)
[Pages domains](https://docs.gitlab.com/api/pages_domains/)
[Personal access tokens](https://docs.gitlab.com/api/personal_access_tokens/)
[Pipeline schedules](https://docs.gitlab.com/api/pipeline_schedules/)
[Pipeline trigger tokens](https://docs.gitlab.com/api/pipeline_triggers/)
[Pipelines](https://docs.gitlab.com/api/pipelines/)
[Plan limits](https://docs.gitlab.com/api/plan_limits/)
[Product analytics](https://docs.gitlab.com/api/product_analytics/)
[Projects](https://docs.gitlab.com/api/projects/)
[Access tokens](https://docs.gitlab.com/api/project_access_tokens/)
[Aliases](https://docs.gitlab.com/api/project_aliases/)
[Badges](https://docs.gitlab.com/api/project_badges/)
[CI/CD variables](https://docs.gitlab.com/api/project_level_variables/)
[Forks](https://docs.gitlab.com/api/project_forks/)
[Import and export](https://docs.gitlab.com/api/project_import_export/)
[Integrations](https://docs.gitlab.com/api/project_integrations/)
[Issue boards](https://docs.gitlab.com/api/boards/)
[Iterations](https://docs.gitlab.com/api/iterations/)
[Labels](https://docs.gitlab.com/api/labels/)
[Members](https://docs.gitlab.com/api/project_members/)
[Markdown uploads](https://docs.gitlab.com/api/project_markdown_uploads/)
[Milestones](https://docs.gitlab.com/api/milestones/)
[Project starring](https://docs.gitlab.com/api/project_starring/)
[Protected branches](https://docs.gitlab.com/api/protected_branches/)
[Protected environments](https://docs.gitlab.com/api/protected_environments/)
[Protected packages](https://docs.gitlab.com/api/project_packages_protection_rules/)
[Protected tags](https://docs.gitlab.com/api/protected_tags/)
[Pull mirroring](https://docs.gitlab.com/api/project_pull_mirroring/)
[Push rules](https://docs.gitlab.com/api/project_push_rules/)
[Relations export](https://docs.gitlab.com/api/project_relations_export/)
[Releases](https://docs.gitlab.com/api/releases/)
[Release links](https://docs.gitlab.com/api/releases/links/)
[Remote mirrors](https://docs.gitlab.com/api/remote_mirrors/)
[Repository storage moves](https://docs.gitlab.com/api/project_repository_storage_moves/)
[Security settings](https://docs.gitlab.com/api/project_security_settings/)
[Snippets](https://docs.gitlab.com/api/project_snippets/)
[Statistics](https://docs.gitlab.com/api/project_statistics/)
[Templates](https://docs.gitlab.com/api/project_templates/)
[Vulnerabilities](https://docs.gitlab.com/api/project_vulnerabilities/)
[Webhooks](https://docs.gitlab.com/api/project_webhooks/)
[Wikis](https://docs.gitlab.com/api/wikis/)
[PyPI](https://docs.gitlab.com/api/packages/pypi/)
[Repositories](https://docs.gitlab.com/api/repositories/)
[Repository files](https://docs.gitlab.com/api/repository_files/)
[Repository submodules](https://docs.gitlab.com/api/repository_submodules/)
[Resource group](https://docs.gitlab.com/api/resource_groups/)
[Resource iteration events](https://docs.gitlab.com/api/resource_iteration_events/)
[Resource label events](https://docs.gitlab.com/api/resource_label_events/)
[Resource milestone events](https://docs.gitlab.com/api/resource_milestone_events/)
[Resource state events](https://docs.gitlab.com/api/resource_state_events/)
[Resource weight events](https://docs.gitlab.com/api/resource_weight_events/)
[Ruby gems](https://docs.gitlab.com/api/packages/rubygems/)
[Runners](https://docs.gitlab.com/api/runners/)
[Runner controllers](https://docs.gitlab.com/api/runner_controllers/)
[Runner controller tokens](https://docs.gitlab.com/api/runner_controller_tokens/)
[Search](https://docs.gitlab.com/api/search/)
[Search migrations](https://docs.gitlab.com/api/search_admin/)
[Secure files](https://docs.gitlab.com/api/secure_files/)
[Service accounts](https://docs.gitlab.com/api/service_accounts/)
[Service Ping](https://docs.gitlab.com/api/usage_data/)
[Sidekiq metrics](https://docs.gitlab.com/api/sidekiq_metrics/)
[Sidekiq queues](https://docs.gitlab.com/api/admin_sidekiq_queues/)
[Snippet repository storage moves](https://docs.gitlab.com/api/snippet_repository_storage_moves/)
[Snippets](https://docs.gitlab.com/api/snippets/)
[Suggestions](https://docs.gitlab.com/api/suggestions/)
[System hooks](https://docs.gitlab.com/api/system_hooks/)
[Tags](https://docs.gitlab.com/api/tags/)
[Terraform registry](https://docs.gitlab.com/api/packages/terraform-modules/)
[To-Do List](https://docs.gitlab.com/api/todos/)
[Token information](https://docs.gitlab.com/api/admin/token/)
[Topics](https://docs.gitlab.com/api/topics/)
[Users](https://docs.gitlab.com/api/users/)
[Version](https://docs.gitlab.com/api/version/)
[Virtual registries cleanup policies](https://docs.gitlab.com/api/virtual_registries_cleanup_policies/)
[Vulnerabilities](https://docs.gitlab.com/api/vulnerabilities/)
[Vulnerability archive export](https://docs.gitlab.com/api/vulnerability_archive_exports/)
[Vulnerability export](https://docs.gitlab.com/api/vulnerability_exports/)
[Vulnerability findings](https://docs.gitlab.com/api/vulnerability_findings/)
[Web commits](https://docs.gitlab.com/api/web_commits/)
[Authentication](https://docs.gitlab.com/api/rest/authentication/)
[Third-party clients](https://docs.gitlab.com/api/rest/third_party_clients/)
[Deprecations and removals](https://docs.gitlab.com/api/rest/deprecations/)
[OpenAPI](https://docs.gitlab.com/api/openapi/openapi_interactive/)
[Automate storage management](https://docs.gitlab.com/user/storage_management_automation/)
[Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
[GraphQL API](https://docs.gitlab.com/api/graphql/)
[OAuth 2.0 identity provider API](https://docs.gitlab.com/api/oauth2/)
[GitLab Duo CLI (duo)](https://docs.gitlab.com/user/gitlab_duo_cli/)
[GitLab CLI (glab)](https://docs.gitlab.com/cli/)
[Editor and IDE extensions](https://docs.gitlab.com/editor_extensions/)
/
  1. [GitLab Docs](https://docs.gitlab.com/)
  2. [Extend](https://docs.gitlab.com/api/)
  3. [REST API](https://docs.gitlab.com/api/rest/)
  4. [Resources](https://docs.gitlab.com/api/api_resources/)
  5. [Projects](https://docs.gitlab.com/api/projects/)
  6. [Import and export](https://docs.gitlab.com/api/project_import_export/)


* * *
# Project import and export API
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Use this API to [migrate a project](https://docs.gitlab.com/user/project/settings/import_export/). If you first migrate the parent group structure with the [group import and export API](https://docs.gitlab.com/api/group_import_export/), you can preserve group-level relationships, such as connections between project issues and group epics.
After using this API, you might want to use the [project-level CI/CD variables API](https://docs.gitlab.com/api/project_level_variables/) to preserve the CI/CD variables for the project.
You must still migrate your [Container Registry](https://docs.gitlab.com/user/packages/container_registry/) over a series of Docker pulls and pushes. Re-run any CI/CD pipelines to retrieve any build artifacts.
Prerequisites:
  * For project exports, see [export a project and its data](https://docs.gitlab.com/user/project/settings/import_export/#export-a-project-and-its-data).
  * For project imports, see [import a project and its data](https://docs.gitlab.com/user/project/settings/import_export/#import-a-project-and-its-data).


## Schedule an export[](https://docs.gitlab.com/api/project_import_export/#schedule-an-export "Permalink")
Start a new export.
The endpoint also accepts an `upload` hash parameter. It contains all the necessary information to upload the exported project to a web server or to any S3-compatible platform. For exports, GitLab:
  * Only supports binary data file uploads to the final server.
  * Sends the `Content-Type: application/gzip` header with upload requests. Ensure that your pre-signed URL includes this as part of the signature.
  * Can take some time to complete the project export process. Make sure the upload URL doesn’t have a short expiration time and is available throughout the export process.
  * Administrators can modify the maximum export file size. By default, the maximum is unlimited (`0`). To change this, edit `max_export_size` using either:
    * [GitLab UI](https://docs.gitlab.com/administration/settings/import_and_export_settings/).
    * [Application settings API](https://docs.gitlab.com/api/settings/#update-application-settings)
  * Has a fixed limit for the maximum import file size on GitLab.com. For more information, see [Account and limit settings](https://docs.gitlab.com/user/gitlab_com/#account-and-limit-settings).


The `upload[url]` parameter is required if the `upload` parameter is present.
For uploads to Amazon S3, refer to [Generating a pre-signed URL for uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) documentation scripts to generate the `upload[url]`. Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/430277), you can only upload files with a maximum file size of 5 GB to Amazon S3.
```
POST /projects/:id/export
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`upload[url]` | string | Yes | The URL to upload the project.
`description` | string | No | Overrides the project description.
`upload` | hash | No | Hash that contains the information to upload the exported project to a web server.
`upload[http_method]` | string | No | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT`.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export" \
  --data "upload[http_method]=PUT" \
  --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<your_access_token>%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"
```

json
```
{
  "message": "202 Accepted"
}
```

## Export status[](https://docs.gitlab.com/api/project_import_export/#export-status "Permalink")
Get the status of export.
```
GET /projects/:id/export
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
shell
```
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export"
```

Status can be one of:
  * `none`: No exports queued, started, finished, or being regenerated.
  * `queued`: The request for export is received, and is in the queue to be processed.
  * `started`: The export process has started and is in progress. It includes:
    * The process of exporting.
    * Actions performed on the resulting file, such as sending an email notifying the user to download the file, or uploading the exported file to a web server.
  * `finished`: After the export process has completed and the user has been notified.
  * `regeneration_in_progress`: An export file is available to download, and a request to generate a new export is in process.


`_links` are only present when export has finished.
`created_at` is the project create timestamp, not the export start time.
json
```
{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "export_status": "finished",
  "_links": {
    "api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export"
  }
}
```

## Export download[](https://docs.gitlab.com/api/project_import_export/#export-download "Permalink")
Download the finished export.
```
GET /projects/:id/export/download
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
shell
```
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/projects/5/export/download"
```

shell
```
ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz
```

## Import a file[](https://docs.gitlab.com/api/project_import_export/#import-a-file "Permalink")
History
  * Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0.
  * `namespace_id` and `namespace_path` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/511053) in GitLab 18.7.


```
POST /projects/import
```

Attribute | Type | Required | Description
---|---|---|---
`file` | string | Yes | The file to be uploaded.
`path` | string | Yes | Name and path for new project.
`name` | string | No | The name of the project to be imported. Defaults to the path of the project if not provided.
`namespace` | integer or string | No | (Deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group. Use `namespace_id` or `namespace_path` instead.
`namespace_id` | integer | No | The ID of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
`namespace_path` | string | No | The path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
`override_params` | hash | No | Supports all fields defined in the [Project API](https://docs.gitlab.com/api/projects/).
`overwrite` | boolean | No | If there is a project with the same path the import overwrites it. Defaults to `false`.
The override parameters passed take precedence over all values defined inside the export file.
To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The `file=` parameter must point to a file on your file system and be preceded by `@`. For example:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --url "https://gitlab.example.com/api/v4/projects/import"
```

cURL doesn’t support posting a file from a remote server. This example imports a project using Python’s `open` method:
python
```
import requests

url =  'https://gitlab.example.com/api/v4/projects/import'
files = { "file": open("project_export.tar.gz", "rb") }
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)
```

json
```
{
  "id": 1,
  "description": null,
  "name": "api-project",
  "name_with_namespace": "Administrator / api-project",
  "path": "api-project",
  "path_with_namespace": "root/api-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": []
}
```

The maximum import file size can be set by the Administrator. It defaults to `0` (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](https://docs.gitlab.com/api/settings/#update-application-settings) or the [**Admin** area](https://docs.gitlab.com/administration/settings/account_and_limit_settings/).
## Import a file from a remote object storage[](https://docs.gitlab.com/api/project_import_export/#import-a-file-from-a-remote-object-storage "Permalink")
  * Status: Beta


History
  * `namespace_id` and `namespace_path` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/511053) in GitLab 18.7.


On GitLab Self-Managed, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](https://docs.gitlab.com/administration/feature_flags/) named `import_project_from_remote_file`. On GitLab.com and GitLab Dedicated, this feature is available.
```
POST /projects/remote-import
```

Attribute | Type | Required | Description
---|---|---|---
`path` | string | Yes | Name and path for the new project.
`url` | string | Yes | URL for the file to import.
`name` | string | No | The name of the project to import. If not provided, defaults to the path of the project.
`namespace` | integer or string | No | (Deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group. Use `namespace_id` or `namespace_path` instead.
`namespace_id` | integer | No | The ID of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
`namespace_path` | string | No | The path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
`overwrite` | boolean | No | Whether to overwrite a project with the same path when importing. Defaults to `false`.
`override_params` | hash | No | Supports all fields defined in the [Project API](https://docs.gitlab.com/api/projects/).
The passed override parameters take precedence over all values defined in the export file.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/remote-import" \
  --data '{"url":"https://remoteobject/file?token=123123","path":"remote-project"}'
```

json
```
{
  "id": 1,
  "description": null,
  "name": "remote-project",
  "name_with_namespace": "Administrator / remote-project",
  "path": "remote-project",
  "path_with_namespace": "root/remote-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}
```

The `Content-Length` header must return a valid number. The maximum file size is 10 GB. The `Content-Type` header must be `application/gzip`.
## Import a single relation[](https://docs.gitlab.com/api/project_import_export/#import-a-single-relation "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) as a [beta](https://docs.gitlab.com/policy/development_stages_support/#beta) in GitLab 16.11 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `single_relation_import`. Disabled by default.
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/455889) in GitLab 17.1. Feature flag `single_relation_import` removed.


This endpoint accepts a project export archive and a named relation (issues, merge requests, pipelines, or milestones) and re-imports that relation, skipping items that have already been imported.
The required project export file adheres to the same structure and size requirements described in [Import a file](https://docs.gitlab.com/api/project_import_export/#import-a-file).
  * The extracted files must adhere to the structure of a GitLab project export.
  * The archive must not exceed the maximum import file size configured by the Administrator.


```
POST /projects/import-relation
```

Attribute | Type | Required | Description
---|---|---|---
`file` | string | Yes | The file to be uploaded.
`path` | string | Yes | Name and path for new project.
`relation` | string | Yes | The name of the relation to import. Must be one of `issues`, `milestones`, `ci_pipelines` or `merge_requests`.
To upload a file from your file system, use the `--form` option, which causes cURL to post data using the header `Content-Type: multipart/form-data`. The `file=` parameter must point to a file on your file system and be preceded by `@`. For example:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --form "relation=issues" \
  --url "https://gitlab.example.com/api/v4/projects/import-relation"
```

json
```
{
  "id": 9,
  "project_path": "namespace1/project1",
  "relation": "issues",
  "status": "finished"
}
```

## Check relation import statuses[](https://docs.gitlab.com/api/project_import_export/#check-relation-import-statuses "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) in GitLab 16.11.


This endpoint fetches the status of any relation imports associated with a project. Because only one relation import can be scheduled at a time, you can use this endpoint to check whether the previous import completed successfully.
```
GET /projects/:id/relation-imports
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
shell
```
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/18/relation-imports"
```

json
```
[
  {
    "id": 1,
    "project_path": "namespace1/project1",
    "relation": "issues",
    "status": "created",
    "created_at": "2024-03-25T11:03:48.074Z",
    "updated_at": "2024-03-25T11:03:48.074Z"
  }
]
```

Status can be one of:
  * `created`: The import has been scheduled, but has not started.
  * `started`: The import is being processed.
  * `finished`: The import has completed.
  * `failed`: The import was not able to be completed.


## Import a file from AWS S3[](https://docs.gitlab.com/api/project_import_export/#import-a-file-from-aws-s3 "Permalink")
History
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350571) in GitLab 15.11. Feature flag `import_project_from_remote_file_s3` removed.
  * `namespace_id` and `namespace_path` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/511053) in GitLab 18.7.


```
POST /projects/remote-import-s3
```

Attribute | Type | Required | Description
---|---|---|---
`access_key_id` | string | Yes |  [AWS S3 access key ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
`bucket_name` | string | Yes |  [AWS S3 bucket name](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) where the file is stored.
`file_key` | string | Yes |  [AWS S3 file key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingObjects.html) to identify the file.
`path` | string | Yes | The full path of the new project.
`region` | string | Yes |  [AWS S3 region name](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html#Regions) where the file is stored.
`secret_access_key` | string | Yes |  [AWS S3 secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#access-keys-and-secret-access-keys).
`name` | string | No | The name of the project to import. If not provided, defaults to the path of the project.
`namespace` | integer or string | No | (Deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group. Use `namespace_id` or `namespace_path` instead.
`namespace_id` | integer | No | The ID of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
`namespace_path` | string | No | The path of the namespace to import the project to. Defaults to the current user’s namespace.

Requires the Maintainer or Owner role on the destination group.
The passed override parameters take precedence over all values defined in the export file.
shell
```
curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/remote-import-s3" \
  --header "PRIVATE-TOKEN: <your gitlab access key>" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Sample Project",
  "path": "sample-project",
  "region": "<Your S3 region name>",
  "bucket_name": "<Your S3 bucket name>",
  "file_key": "<Your S3 file key>",
  "access_key_id": "<Your AWS access key id>",
  "secret_access_key": "<Your AWS secret access key>"
}'
```

This example imports from an Amazon S3 bucket, using a module that connects to Amazon S3:
python
```
import requests
from io import BytesIO

s3_file = requests.get(presigned_url)

url =  'https://gitlab.example.com/api/v4/projects/import'
files = {'file': ('file.tar.gz', BytesIO(s3_file.content))}
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)
```

json
```
{
  "id": 1,
  "description": null,
  "name": "Sample project",
  "name_with_namespace": "Administrator / sample-project",
  "path": "sample-project",
  "path_with_namespace": "root/sample-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}
```

## Import status[](https://docs.gitlab.com/api/project_import_export/#import-status "Permalink")
Get the status of an import.
```
GET /projects/:id/import
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
shell
```
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/import"
```

Status can be one of:
  * `none`
  * `scheduled`
  * `failed`
  * `started`
  * `finished`


If the status is `failed`, it includes the import error message under `import_error`. If the status is `failed`, `started` or `finished`, the `failed_relations` array might be populated with any occurrences of relations that failed to import due to either:
  * Unrecoverable errors.
  * Retries were exhausted. A typical example: query timeouts.


An element’s `id` field in `failed_relations` references the failure record, not the relation. Also, the `failed_relations` array is capped to 100 items.
json
```
{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ]
}
```

When importing from GitHub, the a `stats` field lists how many objects were already fetched from GitHub and how many were already imported:
json
```
{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ],
  "stats": {
    "fetched": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    },
    "imported": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    }
  }
}
```

## Related topics[](https://docs.gitlab.com/api/project_import_export/#related-topics "Permalink")
  * [Migrating projects using file exports](https://docs.gitlab.com/user/project/settings/import_export/).
  * [Project import and export Rake tasks](https://docs.gitlab.com/administration/raketasks/project_import_export/).
  * [Group import and export API](https://docs.gitlab.com/api/group_import_export/)


Was this page helpful?YesNo
Edit this page
  *     * [ Open in Web IDE`.`Quickly and easily edit multiple files. ](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/project_import_export.md)
    * [ View page sourceEdit this file only. ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/project_import_export.md)
    * [ Create an issueSuggest improvements. ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


  * [Schedule an export](https://docs.gitlab.com/api/project_import_export/#schedule-an-export)
  * [Export status](https://docs.gitlab.com/api/project_import_export/#export-status)
  * [Export download](https://docs.gitlab.com/api/project_import_export/#export-download)
  * [Import a file](https://docs.gitlab.com/api/project_import_export/#import-a-file)
  * [Import a file from a remote object storage](https://docs.gitlab.com/api/project_import_export/#import-a-file-from-a-remote-object-storage)
  * [Import a single relation](https://docs.gitlab.com/api/project_import_export/#import-a-single-relation)
  * [Check relation import statuses](https://docs.gitlab.com/api/project_import_export/#check-relation-import-statuses)
  * [Import a file from AWS S3](https://docs.gitlab.com/api/project_import_export/#import-a-file-from-aws-s3)
  * [Import status](https://docs.gitlab.com/api/project_import_export/#import-status)
  * [Related topics](https://docs.gitlab.com/api/project_import_export/#related-topics)


[![GitLab Docs logo](https://docs.gitlab.com/gitlab-logo-footer.svg)](https://docs.gitlab.com/)
  * [Facebook](https://www.facebook.com/gitlab)
  * [LinkedIn](https://www.linkedin.com/company/gitlab-com)
  * [Twitter](https://twitter.com/gitlab)
  * [YouTube](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)

[![Creative Commons License](https://docs.gitlab.com/by-sa.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
Company
  * [About GitLab](https://about.gitlab.com/company/)
  * [View pricing](https://about.gitlab.com/pricing/)
  * [Try GitLab for free](https://about.gitlab.com/free-trial/)


Feedback
  * [View page source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/project_import_export.md)
  * [Edit in Web IDE](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/project_import_export.md)
  * [Contribute to GitLab](https://about.gitlab.com/community/contribute/)
  * [Suggest updates](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


Help & Community
  * [Get certified](https://university.gitlab.com/pages/certifications)
  * [Get support](https://about.gitlab.com/support/)
  * [Post on the GitLab forum](https://forum.gitlab.com/new-topic?title=topic%20title&body=topic%20body&tags=docs-feedback)


Resources
  * [Terms](https://about.gitlab.com/terms/)
  * [Privacy statement](https://about.gitlab.com/privacy/)
  * [Use of generative AI](https://docs.gitlab.com/legal/use_generative_ai/)
  * [Acceptable use of user licenses](https://docs.gitlab.com/legal/licensing_policy/)
  * Cookie Preferences


![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fproject_level_variables%2F&_biz_t=1772174415046&_biz_i=Project-level%20CI%2FCD%20variables%20API%20%7C%20GitLab%20Docs&_biz_n=127&rnd=519678&cdn_o=a&_biz_z=1772174415378)![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fproject_integrations%2F&_biz_t=1772174415127&_biz_i=Project%20integrations%20API%20%7C%20GitLab%20Docs&_biz_n=128&rnd=61577&cdn_o=a&_biz_z=1772174415378)![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fproject_members%2F&_biz_t=1772174415297&_biz_i=Projects%20members%20API%20%7C%20GitLab%20Docs&_biz_n=129&rnd=656856&cdn_o=a&_biz_z=1772174415379)![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fproject_import_export%2F&_biz_t=1772174415377&_biz_i=Project%20import%20and%20export%20API%20%7C%20GitLab%20Docs&_biz_n=130&rnd=916808&cdn_o=a&_biz_z=1772174415380)
![Company Logo](https://cdn.cookielaw.org/logos/aa14a5c8-79e3-442a-8177-464ad850b19d/e46c1d0d-1f66-481f-bc06-5427671431da/253e6fee-c4c0-4b60-bc35-79cdae5dda32/gitlab-logo-100.png)
## Privacy Preference Center
## Privacy Preference Center
  * ### Your Privacy
  * ### Strictly Necessary Cookies
  * ### Functionality Cookies
  * ### Performance and Analytics Cookies
  * ### Targeting and Advertising Cookies
  * ### Ad User Data
  * ### Ad Personalization


#### Your Privacy
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
[Cookie Policy](https://about.gitlab.com/privacy/cookies/)
**User ID:** 42fad8d5-ed56-4786-8d74-3c72635252d2
_This User ID will be used as a unique identifier while storing and accessing your preferences for future._
**Timestamp:** --
#### Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Cookies Details
#### Functionality Cookies
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Cookies Details
#### Performance and Analytics Cookies
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Cookies Details
#### Targeting and Advertising Cookies
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.
Cookies Details
#### Ad User Data
Ad User Data
Sets consent for sending user data to Google for advertising purposes.
Cookies Details
#### Ad Personalization
Ad Personalization
Sets consent for personalized advertising.
Cookies Details
Back Button
### Cookie List
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
  * checkbox label label


Apply Cancel
Confirm My Choices
Allow All
[![Powered by Onetrust](https://cdn.cookielaw.org/logos/static/powered_by_logo.svg)](https://www.onetrust.com/products/cookie-consent/)
