1. Installing
1.1. Using Bikeshed Without A Local Install
1.1.1. Via the Web
If you use Bikeshed infrequently, and are okay with requiring a network roundtrip every time you invoke Bikeshed, you probably want to use the Bikeshed API instead. In return, the API version is always up-to-date, so you don’t have to remember to update things yourself. See § 2 Invoking Bikeshed Without Installing for options.
Note: The remote API has several limitations; most notably, it can’t take multiple files. If you are using custom boilerplates, or include files, you’ll have to run Bikeshed yourself.
1.1.2. Via pipx
If you use Bikeshed infrequently,
but have the prereqs for a local install
(a recent Python 3, and pipx; see below),
you can run an always-up-to-date Bikeshed locally as:
pipx run bikeshed update&& pipx run bikeshed# on subsequent invocations, just call: pipx run bikeshed
This does not have the limitations of the web version;
you can use all the features of Bikeshed,
including custom boilerplates
and include files,
or alternate run modes
like bikeshed watch.
Note: This actually creates a temporary local install,
which automatically disappears after a few days.
It does not add the bikeshed command to your PATH.
However, it generally won’t require manual upgrading;
so long as it’s been long enough for pipx to delete the cached version,
it’ll always grab the newest version of Bikeshed.
1.2. Prereqs
Bikeshed is a Python program, and getting Python working well in modern systems has a few (pretty easy) steps. (These might already all work for you!)
1.2.1. python3
Bikeshed requires Python 3.12 or later. (It’s currently tested up to 3.14.)
To tell what version you have, run:
python3 --version
If it reports 3.12.0 or later, you’re fine.
If it’s earlier, you’ll need to update your local Python version.
There are several ways to do so,
but I recommend pyenv
as a safe and easy method.
https://github.com/pyenv/pyenv#installation gives instructions for installing pyenv on various environments. It also links to the auto-installer, which can make things even easier. Windows users have slightly different instructions, but it links to a windows fork as well.
If you know your way around pyenv already, feel free to do what you’re used to here. Otherwise, it’s probably easiest to just set up 3.14.1 as your "default" Python:
pyenv versions
will list what versions exist, and then
pyenv global3 .14.1
will set 3.14.1 as your "global" version, used by default.
(Substitute in whatever the name of the version you saw in versions was.)
1.2.2. pipx
Installing packages globally is usually a bad (and sometimes insecure!) idea.
They should instead be isolated into "virtual environments".
This used to be a little tricky to set up,
but now pipx makes it very simple.
To install pipx,
your system software distribution might already have it;
for example, distributions using apt can run
sudo apt-get install pipx
If this is not the case for you, see pipx’s install instructions and do whatever it says.
