{"id":50741181,"url":"https://github.com/vincenzoml/podman-minimal","last_synced_at":"2026-06-10T17:02:15.461Z","repository":{"id":354645008,"uuid":"1223818952","full_name":"vincenzoml/podman-minimal","owner":"vincenzoml","description":"Minimal Podman launcher: clean throwaway dev environments from any folder, with Dockerfile/devcontainer autodiscovery.","archived":false,"fork":false,"pushed_at":"2026-06-05T13:39:54.000Z","size":83,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T15:14:32.748Z","etag":null,"topics":["cli","containers","devcontainer","developer-tools","dockerfile","linux","macos","podman","python","rootless","windows"],"latest_commit_sha":null,"homepage":"https://vincenzoml.github.io/podman-minimal/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vincenzoml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T17:26:18.000Z","updated_at":"2026-06-05T13:40:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vincenzoml/podman-minimal","commit_stats":null,"previous_names":["vincenzoml/podman-minimal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vincenzoml/podman-minimal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincenzoml%2Fpodman-minimal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincenzoml%2Fpodman-minimal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincenzoml%2Fpodman-minimal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincenzoml%2Fpodman-minimal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vincenzoml","download_url":"https://codeload.github.com/vincenzoml/podman-minimal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincenzoml%2Fpodman-minimal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34161284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","containers","devcontainer","developer-tools","dockerfile","linux","macos","podman","python","rootless","windows"],"created_at":"2026-06-10T17:02:11.670Z","updated_at":"2026-06-10T17:02:15.451Z","avatar_url":"https://github.com/vincenzoml.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# podman-minimal\n\nMinimal Podman launcher for clean throwaway dev environments from any folder.\n\n[Website](https://vincenzoml.github.io/podman-minimal/) · [Source](https://github.com/vincenzoml/podman-minimal) · [Issues](https://github.com/vincenzoml/podman-minimal/issues)\n\n**Author:** Vincenzo Ciancia ([vincenzoml@gmail.com](mailto:vincenzoml@gmail.com))  \n**License:** [GNU GPLv3 or later](LICENSE)\n\n## Quickstart\n\n```bash\npodman-minimal\n```\n\nFrom any project folder, this opens a clean disposable container shell with your current directory mounted and your host UID/GID preserved.\n\n## Install\n\nLinux / macOS:\n\n```bash\npython3 -c \"import urllib.request as u; exec(u.urlopen('https://raw.githubusercontent.com/vincenzoml/podman-minimal/main/podman-minimal.py').read().decode())\" --install\n```\n\nWindows PowerShell:\n\n```powershell\npy -c \"import urllib.request as u; exec(u.urlopen('https://raw.githubusercontent.com/vincenzoml/podman-minimal/main/podman-minimal.py').read().decode())\" --install\n```\n\nIf `py` is not available yet, install Python first (Microsoft Store is fine), then run the command again.\n\nOn Windows, `--install` defaults to `%LocalAppData%\\Programs\\podman-minimal\\bin`, on mac and linux it defaults to `/usr/local/bin`.\nThe installer writes `podman-minimal.cmd` (launcher) and `podman-minimal.py` in that directory.\nIf that directory is not already in `PATH`, the installer adds it to your user `PATH` automatically.\n\nUser-local install:\n\n```bash\nmkdir -p ~/.local/bin\npython3 -c \"import urllib.request as u; exec(u.urlopen('https://raw.githubusercontent.com/vincenzoml/podman-minimal/main/podman-minimal.py').read().decode())\" --install ~/.local/bin\n```\n\n## Usage\n\n```bash\npodman-minimal\npodman-minimal --image docker.io/library/debian:12 uname -a\npodman-minimal --dockerfile /path/to/Dockerfile\npodman-minimal --root --image docker.io/library/ubuntu:26.04 bash\npodman-minimal --host-root --image docker.io/library/ubuntu:26.04 ls /host\npodman-minimal --nohup run.log -- python3 -m http.server 8080\n```\n\nDefault output is quiet: only Podman and your command speak. Use `-v` / `--verbose` for launcher details (version, image, Dockerfile, build context).\n\n## Default image\n\n- Default base image: `docker.io/library/ubuntu:26.04`.\n- If you run `podman-minimal` without `--image` and no local Dockerfile is discovered, this Ubuntu 26.04 image is pulled (once) and reused.\n- You can always override it per run with `--image`, for example:\n\n```bash\npodman-minimal --image docker.io/library/ubuntu:24.04 bash -lc \"cat /etc/os-release\"\n```\n\n## Useful base images (well-known)\n\nThese are common, broadly useful defaults for different workflows:\n\n- `docker.io/library/ubuntu:26.04`  \n  General-purpose Ubuntu userland; good default for shell tools and apt-based workflows.\n- `docker.io/library/debian:12`  \n  Stable, conservative base for CI-style reproducibility and server-side utilities.\n- `docker.io/library/python:3.12-slim`  \n  Ready-to-use Python runtime with a smaller footprint than full distro images.\n- `docker.io/library/node:22-bookworm`  \n  Good starting point for JavaScript/TypeScript development and build tooling.\n- `docker.io/library/golang:1.23`  \n  Complete Go toolchain image for compiling and testing Go projects.\n- `docker.io/library/rust:1.89`  \n  Includes Rust toolchain and Cargo; useful for Rust build/test loops.\n\nExample overrides:\n\n```bash\npodman-minimal --image docker.io/library/python:3.12-slim python -V\npodman-minimal --image docker.io/library/node:22-bookworm node -v\npodman-minimal --image docker.io/library/golang:1.23 go version\npodman-minimal --image docker.io/library/rust:1.89 rustc --version\n```\n\n## Why not plain podman run?\n\n- No-hassle bootstrap on Linux, macOS, and Windows.\n- Runs with your same UID/GID (`keep-id`) and mounts your current working directory by default.\n- Auto Dockerfile workflow: discover/build/reuse/pull without repeating boilerplate flags.\n- VS Code-compatible devcontainer handling (`.devcontainer` / `.devcontainers` context behavior).\n- Built-in convenience modes: `--nohup`, daemon helpers (Linux), quiet/verbose.\n\nInstead of repeatedly writing:\n\n```bash\npodman run --rm -it -v \"$PWD:/work\" -w /work --userns=keep-id docker.io/library/ubuntu:26.04 bash\n```\n\nyou can use:\n\n```bash\npodman-minimal\n```\n\n## Mount behavior\n\n- Interactive shell and batch command runs mount only your current working directory by default.\n- The launcher does not mount your whole home directory by default.\n- Use `--host-root` to also mount the host root filesystem read-only at `/host` when you need to inspect the full host layout.\n\n```bash\npodman-minimal --host-root -- bash -lc \"ls /host \u0026\u0026 ls /host/Users\"\n```\n\n## Root mode inside container\n\n- Default behavior runs as your host UID/GID (`keep-id`), not as container root.\n- Use `--root` to run interactive shells and batch commands as container root.\n- This is the easiest way to install packages in the default Ubuntu image:\n\n```bash\npodman-minimal --root -- bash -lc \"apt-get update \u0026\u0026 apt-get install -y sudo\"\n```\n\n- `sudo` is often not installed in minimal images; in root mode you usually do not need `sudo` at all.\n- `su -` also depends on tools/users present in the image. Root mode avoids that dependency for admin tasks.\n\n## Lifecycle\n\n```bash\npodman-minimal --version\npodman-minimal --install [DIR]\npodman-minimal --update\npodman-minimal --uninstall [DIR]\n```\n\n## Safety\n\n- Normal runs do not use `sudo`.\n- `--install`, `--update`, and `--uninstall` write/remove only the `podman-minimal` executable.\n- Existing symlink targets are not overwritten during normal install/update; writes use atomic replace.\n- Protected install paths may require `sudo`; use `--install ~/.local/bin` to avoid that.\n- Set `PODMAN_MINIMAL_NO_SUDO=1` to forbid this script from invoking `sudo`.\n- If Podman is missing, the script can use the normal platform installer: `apt/dnf/yum/zypper/pacman` on Linux, Homebrew on macOS, `winget`/`choco` on Windows.\n\n## Dockerfiles\n\nResolution order:\n\n1. `--dockerfile PATH`\n2. Current directory: `Dockerfile`, `.devcontainers/Dockerfile`, `.devcontainer/Dockerfile`, `devcontainer/Dockerfile` (case variants included)\n3. Same list next to the script\n\nFor `.devcontainer/` and `.devcontainers/`, the build context is the parent directory.\n\n## Linux daemon\n\n`--daemon-*` commands are Linux-only and will fail fast on macOS/Windows.\n\n```bash\npodman-minimal --daemon-install python3 -m http.server 8080\npodman-minimal --daemon-status\npodman-minimal --daemon-logs\npodman-minimal --daemon-remove\n```\n\nSystem Quadlet is explicit and root-only:\n\n```bash\nsudo podman-minimal --install --uid 1001 --dir /srv/project --name project\n```\n\n## Other\n\n```bash\npodman-minimal --init-devcontainer\npodman-minimal --help\n```\n\nCopyright © 2026 Vincenzo Ciancia.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincenzoml%2Fpodman-minimal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvincenzoml%2Fpodman-minimal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincenzoml%2Fpodman-minimal/lists"}