Installing PyGPSClient in Linux (here Debian Testing/Trixie)

[Merga189]

In 2023 I installed PyGPSClient on Debian Bookworm. I am not an expert, just a user.
Works fine, but 'update' does not work. So I opened an issue on that.

#177

Closed that issue in the meantime, because that issue seems to be on my side. Sorry. ;-)

Trying to follow the advises I got, started some tests for a fresh installation of PyGPSClient in a Virtualbox VM with Debian Testing/Trixie. Advantage of doing this in a VM: After one test can reset the VM and start 'clean'.

Was pointed to https://www.geeksforgeeks.org/python-virtual-environment/

The first command here my Debian system pointed to 'pipx

~$ pip install virtualenv
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.

If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.

If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.

See /usr/share/doc/python3.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

I found this interesting info https://linuxtldr.com/installing-pipx/
which mentions besides 'virtualenv' and 'pipx' also 'pipenv' environment.

So I tested all 3 ways here.

virtualenv

~$ pipx install virtualenv
~$ pipx ensurepath

### Change terminal, do a logout - login or reboot ###

~$ virtualenv venv
~$ source venv/bin/activate
(venv) user@debian:~$ pipx install pygpsclient
(venv) user@debian:~$ pygpsclient

starts the GUI

pipx

~$ sudo apt install pipx
~$ pipx ensurepath

### Change terminal, do a logout - login or reboot ###

~$ pipx install pygpsclient
~$ pygpsclient

starts the GUI

pipenv

~$ sudo apt install pipenv
~$ mkdir myproject
~$ cd myproject
~/myproject$ pipenv install pygpsclient
~/myproject$ pipenv shell
~/myproject$ pygpsclient

no problem here either

No idea, which one is best. Any suggestions please.

Now to 'update'.

(As I do install and run the actual version, it's a problem trying to update ....)

virtualenv

(venv) user@debian:~$ pipx install upgrade pygpsclient

Fatal error from pip prevented installation. Full pip output in file:
    /home/user/.local/state/pipx/log/cmd_2025-03-16_19.18.12_pip_errors.log

Some possibly relevant errors from pip install:
    ERROR: Could not find a version that satisfies the requirement upgrade (from versions: none)
    ERROR: No matching distribution found for upgrade

Error installing upgrade.

with errrors.log

PIP STDOUT
----------

PIP STDERR
----------
ERROR: Could not find a version that satisfies the requirement upgrade (from versions: none)
ERROR: No matching distribution found for upgrade

pipx

~$ pipx install upgrade pygpsclient

with identical error message and log as virtualenv

pipenv

(myproject) user@debian:~/myproject$ pipenv upgrade pygpsclient

Building requirements...
Resolving dependencies...
✔ Success!
Building requirements...
Resolving dependencies...
✔ Success!
(myproject) user@debian:~/myproject$

is different.

Which to choose and how to test?

br Karl

[semuadmin]

@Merga189,

Ok where to start...

Please understand that the error: externally-managed-environment warning is a constraint imposed by your Debian Python environment, not a PyGPSClient issue. It is essentially prompting you to install Python packages into discrete virtual environments rather than a single system-wide environment, as is generally considered best practice. The PyGPSClient README outlines exactly how to do this using pip and virtualenv/venv - you simply need to follow these instructions.

To use virtual environments, you need to have a package called venv or virtualenv installed. venv is normally pre-installed with Python>=3.3. virtualenv generally needs to be installed manually, but it offers additional functionality which can be useful in advanced situations.

I personally prefer to use virtualenv, but venv will do the job just as well (in the present context) and the syntax is more or less identical. You can substitute virtualenv for venv in any of the following commands. If you want to install virtualenv into an 'externally managed environment' in Debian you can use the following apt command, exactly as the information message you quote above tells you:

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.

sudo apt install python3-virtualenv

This will install virtualenv along with its Python3 dependencies. You then follow the instructions EXACTLY AS WRITTEN IN THE README to install PyGPSClient into a virtual environment:

python3 -m virtualenv env
source env/bin/activate
python3 -m pip install --upgrade pygpsclient

env is just an arbitrary name - you could call it pygpsclient or karl if you prefer. To upgrade the package at a later date, you simply activate the same virtual environment and type exactly the same pip command:

source env/bin/activate
python3 -m pip install --upgrade pygpsclient

NB python3 -m pip install --upgrade always installs the latest available version of a package - you can use this command both for the initial installation and for any subsequent upgrades.

THAT'S IT!

e.g. here's a (truncated) log where I install PyGPSClient version 1.5.0 and then upgrade it to the latest version 1.5.3 using pip and virtualenv:

➜  ~ python3 -m virtualenv env
created virtual environment CPython3.13.2.final.0-64 in 240ms
...
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
➜  ~ source env/bin/activate
(env) ➜  ~ python3 -m pip install pygpsclient==1.5.0
Collecting pygpsclient==1.5.0
  Using cached pygpsclient-1.5.0-py3-none-any.whl.metadata (61 kB)
...
Successfully installed Pillow-11.1.0 certifi-2025.1.31 cffi-1.17.1 charset-normalizer-3.4.1 cryptography-44.0.2 idna-3.10 paho-mqtt-2.1.0 pycparser-2.22 pygnssutils-1.1.9 pygpsclient-1.5.0 pynmeagps-1.0.46 pyrtcm-1.1.4 pyserial-3.5 pyspartn-1.0.5 pyubx2-1.2.50 pyubxutils-1.0.2 requests-2.32.3 urllib3-2.3.0
(env) ➜  ~ deactivate
➜  ~ source env/bin/activate                  
(env) ➜  ~ python3 -m pip install --upgrade pygpsclient
Requirement already satisfied: pygpsclient in ./env/lib/python3.13/site-packages (1.5.0)
Collecting pygpsclient
 ...
Installing collected packages: pygpsclient
  Attempting uninstall: pygpsclient
    Found existing installation: pygpsclient 1.5.0
    Uninstalling pygpsclient-1.5.0:
      Successfully uninstalled pygpsclient-1.5.0
Successfully installed pygpsclient-1.5.3
(env) ➜  ~ deactivate

---

Third-party tools like pipx and pipenv are essentially 'wrappers' around the native pip and virtualenv commands which perform exactly the same steps. They save you a few keystrokes, but they do nothing that you can't do with the native pip and venv/virtualenv tools. If you're relatively new to Python, it may be useful to familiarise yourself with the native pip and venv/virtualenv commands as this will help you understand what's going on under the covers.

If you want to use pipx, then the install command is:

pipx install pygpsclient

The subsequent upgrade command is:

pipx upgrade pygpsclient

(NB NOT pipx install upgrade pygpsclient - you're confusing pipx syntax with pip syntax - pipx thinks you're trying to install a package called 'upgrade')

e.g. here's a log where I install PyGPSClient version 1.5.0 and then upgrade it to the latest version 1.5.3 using pipx:

➜  ~ pipx install pygpsclient==1.5.0
  installed package pygpsclient 1.5.0, installed using Python 3.12.7
  These apps are now globally available
    - pygpsclient
done! ✨ 🌟 ✨
➜  ~ pipx upgrade pygpsclient
upgraded package pygpsclient from 1.5.0 to 1.5.3 (location:
/home/semuadmin/.local/share/pipx/venvs/pygpsclient)

---

BOTTOM LINE - simply follow the instructions in the PyGPSClient README and you should be fine!

[Merga189]

Thank you for taking your time in substantially answering on my 'experiments' here.

I followed the recommendation in README for a test.

'It is highly recommended to use the latest official Python.org installation package for your platform, rather than any pre-installed version.'

Downloaded and unpacked the package and installed it

./configure
    make
    make test
    sudo make install

So I get here a second 3.13.2 in /usr/local/ besides my Debian python 3.13.2.

Tried to purge the Debian python before installing the 'offical' python, but that seems not to be possible, because system data (GUI data) would also be purged.

And having two python version (same! versions) on my system? That is not an idea which pleases me. So for the moment I'll leave it with the Debian python, serviced, managed and updated by the Debian team.

virtualenv

~$ sudo apt install virtualenv                            // OK, as virtualenv depends on python3-virtualenv
~$ virtualenv venv
~$ source venv/bin/activate
(venv) user@debian:~$ pip install pygpsclient==1.5.0
(venv) user@debian:~$ pip install --upgrade pygpsclient         // '--upgrade' here

works and updates. Creates two folders

user@debian:~/venv$ 
user@debian:~/.local/share/virtualenv$

Starting pygpsclient needs a script.

pipenv

~$ sudo apt install pipenv
~$ mkdir myproject
~$ cd myproject
myproject$ pipenv install pygpsclient==1.5.0
myproject$ pipenv shell
myproject$ pygpsclient
myproject$ pipenv update pygpsclient                            // 'update'

works and updates. Creates three folders

user@debian:~/myproject
user@debian:~/.local/share/virtualenv$ 
user@debian:~/.local/share/virtualenvs$

Starting pygpsclient needs a script.

pipx

~$ sudo apt install pipx
~$ pipx ensurepath
~$ pipx install pygpsclient==1.5.0
~$ pipx upgrade pygpsclient                                     // 'and a simple 'upgrade' here

works and updates. Creates one folder

user@debian:~/.local/share/pipx/venvs/pygpsclient/

and starts direct from the terminal.

For the moment I learned a lot and I'll keep my notes on this. Try for the moment with the Debian python and pipx way (I am lazy ;-) ).
One folder to have an eye on and starting direct.

Thank you again for this great alternative to u-center, a software I have to switch over to Windows (I don't like) and which over the years I still have problems in getting familiar with.

Best regard s from Germany - Karl

[semuadmin]

@Merga189

Bear in mind that you're coming at this purely from a Debian perspective, whereas I need to consider the many thousands of other PyGPSClient users who are using other operating systems, including the various generations of Windows, MacOS and other Linux or 'Posix' flavours. My installation instructions are intended to be 'platform agnostic', which is why I advocate native Python tools like pip or venv rather than third party tools like pipx or pipenv, as far as is practicable. While it may be relatively trivial to install e.g. pipx in Debian (if you have superuser privileges), this is NOT necessarily the case in Windows or MacOS.

Tried to purge the Debian python before installing the 'offical' python, but that seems not to be possible, because system data (GUI data) would also be purged.

And having two python version (same! versions) on my system? That is not an idea which pleases me. So for the moment I'll leave it with the Debian python, serviced, managed and updated by the Debian team.

The reason I recommend installing an official python.org Python is that the version of Python which comes pre-installed with some Linux distros (and some older MacOS editions) is NOT a full Python environment - it's there purely to serve any Python utilities that might be bundled with the distro, and often omits standard packages like pip and tkinter. In addition, the official version will include the latest bug fixes, security patches and performance enhancements.

There's absolutely no technical reason why you can't have more than one Python environment on your machine - this is actually very common - but it can obviously cause confusion if you're not careful about which environment you're installing new packages into. Explicitly setting the appropriate $PATH(s) in your shell resource file (.bashrc or whatever) should ensure that the correct Python interpreter is referenced. This is also why the README recommends using the syntax python3 -m virtualenv ... and python3 -m pip ... rather than just virtualenv ... or pip ..., as this is one of the ways you can ensure you're unambiguously referencing the correct Python interpreter.

~$ virtualenv venv
~$ source venv/bin/activate

I would VERY STRONGLY advise against calling your virtual environment 'venv', as this risks causing confusion with the native Python venv package. If you're creating a virtual environment for pygpsclient, calling it 'pygpsclient' might be more intuitive. This is effectively what pipx does by default.

virtualenv
Starting pygpsclient needs a script.

I'm unclear where you're getting this from, as it's simply not true. If you follow the README instructions for venv/virtualenv, it will create a high level directory containing /bin, /include and /lib subdirectories (pipx will do exactly the same thing). The pygpsclient executable is placed in the env/bin folder (e.g. /home/user/env/bin/pygpsclient). Provided this env/bin folder is in your $PATH, all you need to do to run pygpsclient is simply type 'pygpsclient' at the terminal - exactly as I have stated in the README.

Where pipx differs from pip is that pipx will install the pygpsclient executable into a separate ~/.local folder e.g. /home/user/.local/bin/pygpsclient. This folder is typically (but not necessarily!) already in the user's $PATH, which is why you can invoke pygpsclient directly from the terminal. Running pipx ensurepath explicitly adds this folder to the user $PATH if it's not already there.