Import container images

Import container images into your project's image library to deploy them without a Northflank build. You can copy an image from a registry, upload an archive, or push an image with Docker.

Imports store a copy in Northflank's registry. To deploy directly from another registry, use an external image.

Requirements

• Your role needs Images → Read and Images → Import permissions for the project.
• A Linux image for linux/amd64 or linux/arm64. The image must support your deployment's architecture.
• The image and deployment must be in the same project. Import the image into each project that needs it.

In your project, select Images under Config & data. Select Import image.

Choose a name and tag

Use a lowercase image name, such as api, to group versions of the same image.

Give each version a unique tag, such as release-2026-10-19. You cannot overwrite a version tag or import an image with the destination tag latest. The Latest selection resolves to the newest ready version.

Import from a registry

The source registry must use HTTPS and a publicly routable address. A registry on a private network is not supported. For a private image, you need matching saved credentials with pull access and access to this project. You also need permission to read those credentials.

1. Select From Registry.
2. Enter a Source image reference, such as nginx:1.28 or ghcr.io/example/api:v1.
3. For a private image, select the appropriate registry credentials.
4. Enter the Destination image name and Destination image tag.
5. Select Import image.

Closing the dialog does not cancel a submitted import.

Upload an archive

Use an uncompressed tar archive in Docker (docker-archive) or OCI image layout (oci-archive) format. For example, save a local image:

docker save -o image.tar api:v1

1. Select Upload Archive and choose your file in Image archive.
2. Enter the destination Image name and Image tag.
3. If the archive contains several images, select one in Image in archive.
4. Select Upload image.

Keep the page open until the transfer completes. Cancel transfer stops an active transfer. If Northflank already received the image, the import can finish after cancellation.

Push with Docker

1. Select Docker Push to get commands for your project.
2. Create an API token with Images → Import permission and access to the project.
3. Run the displayed login command with your Northflank username. Enter the token when Docker prompts for a password.
4. Run the displayed tag and push commands for your local image and destination name and tag.

For example, replace the username, project ID, and local image reference (api:v1) before running:

docker login -u USERNAME registry.northflank.com
docker tag api:v1 registry.northflank.com/PROJECT_ID/api:v1
docker push registry.northflank.com/PROJECT_ID/api:v1

Deploy and update an image

Wait until the image shows Ready in Images. Transfer completion alone does not make an image ready. If it shows Failed, open the image to read the error.

1. Create a deployment service or job in the same project.
2. Select Northflank as the deployment source.
3. In Link image source, select the imported image in Image source.
4. If Group appears, select No group for imported images.
5. Select a specific Image tag, or Latest for the newest ready version.
6. Complete the resource configuration and create the service or job.

To publish an update, import or push the same image name with a new version tag. Services that use Latest with continuous deployment enabled receive new ready versions automatically.

To update a service manually, change its image or tag. This starts a rollout restart:

1. Select Edit image source on the service overview.
2. Select Northflank and choose the image and tag.
3. Select Update & rollout restart.
4. Wait for the deployment to become ready.

Open a ready image in Images to view its architecture and Pull Docker image commands. Pulling an imported image requires an API token with Images → Read permission.