Working with the PyPI registry
Create a package
Before you can publish and install a package from the PyPI registry, you will need to create one in Bitbucket first:
Select the Create button on the top navigation bar to open the Create dropdown menu.
Select Package from the Create dropdown.
Select PyPI from the Package type dropdown.
Provide a package name for the package.
Select the Repository to link to dropdown and select the repository that you want to link the package to. Note: The package inherits the permissions of the repository which then grants users the same permissions to access the package.
Select Submit to create your package.
Repository admins only
If you are not the admin of the workspace but you are a repository admin, you will see the repositories that you can add a package to in the This repository section of the Create dropdown menu.
Package manager support
We support the twine, pip, uv and Poetry package managers. Other package managers may work with the registry but aren’t officially supported.
Authentication
Publishing and installing PyPI packages from the Bitbucket package registry requires you to authenticate your client with an Atlassian API token.
To authenticate to the Bitbucket package registry within Bitbucket Pipelines, you can use BITBUCKET_PACKAGES_USERNAME and BITBUCKET_PACKAGES_TOKEN environment variables available to each step in your Bitbucket Pipeline runs. Learn more about using variables to integrate with Pipelines.
twine
Add the following to your .pypirc file. Create a new file if one doesn’t exist.
[distutils]
index-servers =
bitbucket
[bitbucket]
repository = https://pypi.apkg.io/<workspace-slug>
username = <atlassian-email>
password = <atlassian-api-token>uv
Run the following command to configure credentials for the Bitbucket package registry:
echo '<atlassian-api-token>' | uv auth login https://pypi.apkg.io/<workspace-slug> --username <atlassian-email> --password -Poetry
Run the following command to configure credentials for the Bitbucket package registry:
poetry config http-basic.bitbucket <atlassian-email> <atlassian-api-token>When a PyPI package version is published through the native Bitbucket Pipelines authentication, the package version details includes the pipeline that published it. This gives teams better traceability from a published artifact back to the build that created it.
Publishing an PyPI package to the registry
twine
Run the following command to publish to the Bitbucket package registry:
twine upload --repository bitbucket --config-file .pypirc <dist-files>uv
Add the following to your pyproject.toml file.
[[tool.uv.index]]
name = "bitbucket"
publish-url = "https://pypi.apkg.io/<workspace-slug>"
explicit = truePublish the package.
uv publish --index bitbucketPoetry
Add the following to your pyproject.toml file.
[[tool.poetry.source]]
name = "bitbucket"
url = "https://pypi.apkg.io/<workspace-slug>"
priority = "explicit"Publish the package.
poetry publish --repository bitbucketInstalling an PyPI package
pip
Run the following command to install the package.
pip install --index-url https://<atlassian-email>:<atlassian-api-token>@pypi.apkg.io <package-name>==<package-version>uv
Add the following to your pyproject.toml file.
[tool.uv.sources]
<package-name> = { index = "bitbucket" }
[[tool.uv.index]]
name = "bitbucket"
url = "https://pypi.apkg.io/<workspace-slug>"
explicit = trueInstall the package.
uv add <package-name>==<package-version>Poetry
Add the following to your pyproject.toml file.
[[tool.poetry.source]]
name = "bitbucket"
url = "https://pypi.apkg.io/<workspace-slug>"
priority = "explicit"Install the package.
poetry add --source bitbucket <package-name>==<package-version>View PyPI packages
The PyPI packages within your registry can be viewed from the workspace, project, and repository. You will see a list of PyPI packages along with other package types that have been published to your workspace, project, or repository.
To view the PyPI packages within the workspace, select Packages on the left sidebar. This opens the Packages page which lists all the PyPI packages within the workspace.
To view the PyPI packages within a project, select Packages on the left sidebar from within the project in which you want to see a list of PyPI packages.
To view the PyPI packages within a repository, select Packages on the left sidebar within the repository in which you want to see a list of PyPI packages.
Viewing PyPI package details
Display a package: Select the PyPI package name from the list of packages to see details about that PyPI package.
Display a version: Select the version to see details specific to that version.
Delete an PyPI package and version
In Bitbucket Cloud, you can delete either a PyPI version or the entire PyPI package, including all of its versions.
Delete an PyPI version
Only users with repository write or admin permissions can delete an PyPI version.
Deleting an PyPI version permanently removes it from Bitbucket Cloud. Once it is deleted, the version can no longer be installed and storage will be freed up soon after. To delete an PyPI version:
From the packages list view under the workspace, project, or repository, select the PyPI package containing the version you want to delete.
Find the version you want to delete in the versions list view, and open the Actions menu.
Select Delete version, then select Delete.
Delete an PyPI package
Only repository admins can delete an PyPI package.
Deleting an PyPI package permanently removes it and all of its versions from packages. Once deleted, the PyPI package and all its versions can no longer be installed and storage will be freed up soon after. To delete an PyPI package:
From the packages list view under the workspace, project, or repository, select the PyPI package you want to delete.
Find the package you want to delete in the versions list view, and open the Actions menu
Select Delete package, then select Delete.
Was this helpful?