chore(main): Migrate to uv

.devcontainer/Dockerfile

@@ -1,20 +1,13 @@
-FROM mcr.microsoft.com/devcontainers/python:1-3.11-bookworm
+ARG UV_VERSION=latest
 
 
-RUN \
-    apt update && apt install bash-completion -y && \
-    pip install pre-commit && \
-    curl -sSL https://install.python-poetry.org | POETRY_HOME=/home/vscode/.local python3 -
+FROM ghcr.io/astral-sh/uv:$UV_VERSION AS uv
 
 
-RUN  \
-    echo >> /home/vscode/.bashrc && \
-    # add completions to bashrc
-    # see how ubuntu does it for reference:
-    # https://git.launchpad.net/ubuntu/+source/base-files/tree/share/dot.bashrc
-    # https://stackoverflow.com/a/68566555
-    echo 'if [ -f /etc/bash_completion ] && ! shopt -oq posix; then' >> /home/vscode/.bashrc && \
-    echo '    . /etc/bash_completion' >> /home/vscode/.bashrc && \
-    echo 'fi' >> /home/vscode/.bashrc && \
-    echo >> /home/vscode/.bashrc && \
-    echo '. <(poetry completions)' >> /home/vscode/.bashrc
+FROM mcr.microsoft.com/vscode/devcontainers/base:debian
+
+ENV PYTHONDONTWRITEBYTECODE=True \
+    PYTHONUNBUFFERED=True \
+    UV_LINK_MODE=copy
+
+COPY --from=uv --chown=vscode: /uv /uvx /bin/

.devcontainer/commands/post-create-command.sh

@@ -1,4 +1,4 @@
 echo "Running post-create-command.sh"
 
 pre-commit install
-poetry install --all-extras
+uv sync --all-extras

.devcontainer/devcontainer.json

@@ -5,7 +5,7 @@
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
 	"build": {
 		// Path is relative to the devcontainer.json file.
-		// We prebuild the image to get poetry into the image
+		// We prebuild the image to get uv into the image
 		// This saves the user a bit of time, when re-opening containers
 		"dockerfile": "Dockerfile"
 	},

.github/ISSUE_TEMPLATE/question.md

@@ -31,9 +31,9 @@ uname -a
 echo "------"
 docker info
 echo "------"
-poetry run python --version
+uv run python --version
 echo "------"
-poetry show --tree
+uv tree
 ```
 
 ```bash

.github/PULL_REQUEST_TEMPLATE/new_container.md

@@ -29,8 +29,8 @@ It helps reduce unnecessary work for you and the maintainers!
   - Your module has a `README.rst` and hooks in the `.. auto-class` and `.. title` of your container
   - Implement the new feature (typically in `__init__.py`) and corresponding tests.
 - [ ] Your module is added in `pyproject.toml`
-  - it is declared under `tool.poetry.packages` - see other community modules
-  - it is declared under `tool.poetry.extras` with the same name as your module name,
+  - it is declared under `tool.hatch.build.targets.wheel` - see other community modules
+  - it is declared under `project.optional-dependencies` with the same name as your module name,
     we still prefer adding _NO EXTRA DEPENDENCIES_, meaning `mymodule = []` is the preferred addition
     (see the notes at the bottom)
 - [ ] Your branch is up-to-date (or your branch will be rebased with `git rebase`)

.github/actions/setup-env/action.yml

@@ -10,11 +10,7 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Setup Poetry
-      run: pipx install poetry
-      shell: bash
-    - name: Setup python ${{ inputs.python-version }}
-      uses: actions/setup-python@v5
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
       with:
         python-version: ${{ inputs.python-version }}
-        cache: poetry

.github/workflows/ci-community.yml

@@ -2,6 +2,10 @@
 
 name: modules
 
+env:
+  UV_FROZEN: "1"  # use lock file as is
+  UV_NO_EDITABLE: "1"  # test the build package, not the dev installation
+
 on:
   push:
     branches: [ main ]
@@ -54,7 +58,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Python dependencies
-        run: poetry install -E ${{ matrix.module }}
+        run: uv sync --extra ${{ matrix.module }}
       - name: Run tests
         run: make modules/${{ matrix.module }}/tests
       - name: Run doctests

.github/workflows/ci-core.yml

@@ -2,6 +2,10 @@
 
 name: core
 
+env:
+  UV_FROZEN: "1"   # use lock file as is
+  UV_NO_EDITABLE: "1"  # test the build package, not the dev installation
+
 on:
   push:
     branches: [main]
@@ -22,9 +26,9 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Python dependencies
-        run: poetry install --all-extras
+        run: uv sync --all-extras
       - name: Run twine check
-        run: rm -f LICENSE.txt && poetry build && poetry run twine check dist/*.tar.gz
+        run: uv build && uv run twine check dist/*
       - name: Run tests
         run: make core/tests
       - name: Rename coverage file
@@ -47,7 +51,7 @@ jobs:
       - name: Set up Python
         uses: ./.github/actions/setup-env
       - name: Install Python dependencies
-        run: poetry install --all-extras
+        run: uv sync --all-extras
       - name: "Download coverage artifacts"
         uses: actions/download-artifact@v4
         with:

.github/workflows/ci-lint.yml

@@ -2,6 +2,10 @@
 
 name: lint
 
+env:
+  UV_FROZEN: "1"   # use lock file as is
+  UV_NO_EDITABLE: "1"  # test the build package, not the dev installation
+
 on:
   push:
     branches: [main]
@@ -15,18 +19,14 @@ jobs:
       - uses: actions/checkout@v4
       - name: Setup Env
         uses: ./.github/actions/setup-env
-        with:
-          python-version: "3.13"
-      - name: Install Python dependencies
-        run: poetry install --with dev --no-interaction
       - name: Execute pre-commit handler
         continue-on-error: true
         run: |
-          poetry run pre-commit run check-toml
-          poetry run pre-commit run trailing-whitespace
-          poetry run pre-commit run end-of-file-fixer
-          poetry run pre-commit run ruff
-          poetry run pre-commit run ruff-format
+          uv run pre-commit run check-toml
+          uv run pre-commit run trailing-whitespace
+          uv run pre-commit run end-of-file-fixer
+          uv run pre-commit run ruff
+          uv run pre-commit run ruff-format
       - name: Execute mypy
         run: |
           make mypy-core-report

.github/workflows/release-please.yml

@@ -1,5 +1,9 @@
 name: Release Please
 
+env:
+  UV_FROZEN: "1"   # use lock file as is
+  UV_NO_EDITABLE: "1"  # test the build package, not the dev installation
+
 on:
   push:
     branches: [ main ]
@@ -28,8 +32,8 @@ jobs:
       - name: Set up Python
         uses: ./.github/actions/setup-env
       - name: build package
-        run: poetry build
-      # this action uploads packages from the `dist/` directory, which poetry has built in the previous step
+        run: uv build
+      # this action uploads packages from the `dist/` directory, which uv has built in the previous step
       # usable once we set up trusted publishing, see https://docs.pypi.org/trusted-publishers/using-a-publisher/
       - name: push package
         uses: pypa/gh-action-pypi-publish@release/v1

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
     hooks:
       - id: mypy
         name: mypy
-        entry: poetry run mypy
+        entry: uv run mypy
         args: ["--config-file", "pyproject.toml"]
         files: "core"  # start with the core being type checked
         language: system

.readthedocs.yml

@@ -1,19 +1,21 @@
 # Read the Docs configuration file (see https://docs.readthedocs.io/en/stable/config-file/v2.html
 # for details).
-
+# https://docs.readthedocs.com/platform/stable/build-customization.html#install-dependencies-with-uv
 version: 2
 
 sphinx:
    configuration: conf.py
 
 build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.10"
-
-  # https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-1143587902s
-  jobs:
-    post_install:
-      - pip install poetry==2.1.2  # match version from poetry.lock
-      - poetry config virtualenvs.create false
-      - poetry install --all-extras
+   os: ubuntu-24.04
+   tools:
+      python: "3.13"
+   jobs:
+      pre_create_environment:
+         - asdf plugin add uv
+         - asdf install uv latest
+         - asdf global uv latest
+      create_environment:
+         - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+      install:
+         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --all-extras --group docs

Dockerfile

@@ -1,29 +1,11 @@
 ARG PYTHON_VERSION=3.10
-FROM python:${PYTHON_VERSION}-slim-bookworm
-
-ENV POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_IN_PROJECT=1 \
-    POETRY_VIRTUALENVS_CREATE=1 \
-    POETRY_CACHE_DIR=/tmp/poetry_cache
+# see https://docs.astral.sh/uv/guides/integration/docker/ for available images
+FROM ghcr.io/astral-sh/uv:python${PYTHON_VERSION}-bookworm-slim
 
 WORKDIR /workspace
-RUN pip install --upgrade pip \
-    && apt-get update \
-    && apt-get install -y freetds-dev \
-    && apt-get install -y make \
-    # no real need for keeping this image small at the moment
-    && :; # rm -rf /var/lib/apt/lists/*
-
-# install poetry
-RUN bash -c 'python -m venv /opt/poetry-venv && source $_/bin/activate && pip install poetry && ln -s $(which poetry) /usr/bin'
-
-# install dependencies with poetry
-COPY pyproject.toml .
-COPY poetry.lock .
-RUN poetry install --all-extras --with dev --no-root
 
 # copy project source
 COPY . .
 
-# install project with poetry
-RUN poetry install --all-extras --with dev
+# install dependencies with uv
+RUN uv sync --frozen --all-extras

Makefile

@@ -12,43 +12,43 @@ DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES}))
 
 
 install:  ## Set up the project for development
-	poetry install --all-extras
-	poetry run pre-commit install
+	uv sync --all-extras
+	uv run pre-commit install
 
 build:  ## Build the python package
-	poetry build && poetry run twine check dist/*
+	uv build && uv run twine check dist/*
 
 tests: ${TESTS}  ## Run tests for each package
 ${TESTS}: %/tests:
-	poetry run pytest -v --cov=testcontainers.$* $*/tests
+	uv run pytest -v --cov=testcontainers.$* $*/tests
 
 coverage:  ## Target to combine and report coverage.
-	poetry run coverage combine
-	poetry run coverage report
-	poetry run coverage xml
-	poetry run coverage html
+	uv run coverage combine
+	uv run coverage report
+	uv run coverage xml
+	uv run coverage html
 
 lint:  ## Lint all files in the project, which we also run in pre-commit
-	poetry run pre-commit run -a
+	uv run pre-commit run --all-files
 
 mypy-core:  ## Run mypy on the core package
-	poetry run mypy --config-file pyproject.toml core
+	uv run mypy --config-file pyproject.toml core
 
 mypy-core-report:  ## Generate a report for mypy on the core package
-	poetry run mypy --config-file pyproject.toml core | poetry run python scripts/mypy_report.py
+	uv run mypy --config-file pyproject.toml core | uv run python scripts/mypy_report.py
 
 docs: ## Build the docs for the project
-	poetry run sphinx-build -nW . docs/_build
+	uv run --all-extras sphinx-build -nW . docs/_build
 
 # Target to build docs watching for changes as per https://stackoverflow.com/a/21389615
 docs-watch :
-	poetry run sphinx-autobuild . docs/_build # requires 'pip install sphinx-autobuild'
+	uv run sphinx-autobuild . docs/_build # requires 'pip install sphinx-autobuild'
 
 doctests: ${DOCTESTS}  ## Run doctests found across the documentation.
-	poetry run sphinx-build -b doctest . docs/_build
+	uv run --all-extras sphinx-build -b doctest . docs/_build
 
 ${DOCTESTS}: %/doctests:  ##  Run doctests found for a module.
-	poetry run sphinx-build -b doctest -c doctests $* docs/_build
+	uv run --all-extras sphinx-build -b doctest -c doctests $* docs/_build
 
 
 clean:  ## Remove generated files.
@@ -74,36 +74,6 @@ help:  ## Display command usage
 
 ## --------------------------------------
 
-DOCS_CONTAINER=mkdocs-container
-DOCS_IMAGE=mkdocs-poetry
-DOCS_DOCKERFILE := Dockerfile.docs
-
-.PHONY: clean-docs
-clean-docs:
-	@echo "Destroying docs"
-	@if docker ps -a --format '{{.Names}}' | grep -q '^$(DOCS_CONTAINER)$$'; then \
-		docker rm -f $(DOCS_CONTAINER); \
-	fi
-	@if docker images -q $(DOCS_IMAGE) | grep -q .; then \
-		docker rmi $(DOCS_IMAGE); \
-	fi
-
-.PHONY: docs-ensure-image
-docs-ensure-image:
-	@if [ -z "$$(docker images -q $(DOCS_IMAGE))" ]; then \
-		docker build -f $(DOCS_DOCKERFILE) -t $(DOCS_IMAGE) . ; \
-	fi
-
 .PHONY: serve-docs
-serve-docs: docs-ensure-image
-	docker run --rm --name $(DOCS_CONTAINER) -it -p 8000:8000 \
-		-v $(PWD):/testcontainers-go \
-		-w /testcontainers-go \
-		$(DOCS_IMAGE) bash -c "\
-			cd docs && poetry install --no-root && \
-			poetry run mkdocs serve -f ../mkdocs.yml -a 0.0.0.0:8000"
-
-# Needed if dependencies are added to the docs site
-.PHONY: export-docs-deps
-export-docs-deps:
-	cd docs && poetry export --without-hashes --output requirements.txt
+serve-docs:
+	uv run mkdocs serve -f mkdocs.yml -a 127.0.0.1:8000

README.md

@@ -1,4 +1,4 @@
-[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 ![PyPI - Version](https://img.shields.io/pypi/v/testcontainers)
 [![PyPI - License](https://img.shields.io/pypi/l/testcontainers.svg)](https://github.com/testcontainers/testcontainers-python/blob/main/LICENSE)

core/testcontainers/core/container.py

@@ -35,6 +35,7 @@ class Mount(TypedDict):
 
 class DockerContainer:
     """
+
     Basic container object to spin up Docker instances.
 
     Args: