Python

The default Python distribution for Ubuntu is installed. You can start it with python3. To keep the system as flexible as possible for all users, no extra packages have been installed except pip and venv. To use other packages, follow the instructions below:

Dependency management with uv

With a virtual environment, you create an isolated Python environment in which you can install other packages easily. You can create as many virtual environments as needed, typically one per project. This allows you to install different versions of packages that might be specifically needed for an application or might conflict with other packages.

In this guide we will make use of the uv package manager, which handles both the creation of virtual environments as well as management of any dependencies. To use uv it must first be installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Starting a new Python project

If you are starting a new project, you can initialize it using uv init.

mkdir project
uv init

This will generate initial files for executing your Python project. The Python version used is written to .python-version.

Installing a specific Python version

If the installed python version is not the one you wish, or it causes dependency issues with existing dependencies, it is straightforward to install your desired Python version. To change the project’s python version, use

uv python upgrade [version]

pyproject.toml contains metadata about your project. When sharing the project, it is recommended to update this information, but for now you may keep it as-is.

Running Python files

You may be used to using Python [FILENAME] or Python3 [FILENAME] to execute your files. Using uv, this should be adjusted to uv run python [FILENAME]. For example, to run main.py generated after uv init, use

uv run python main.py

This command does several things at once. First of all, it solves for the current dependencies and saves the required versions in a uv.lock file. Second, it downloads and installs these packages and the Python version used into the virtual environment folder .venv. Finally, it invokes the Python version inside the virtual environment and runs the file specified from the current working directory.

Installing packages

To install packages, many tutorials will tell you to use either pip install or conda install. These are different package managers, so when using uv it is not recommended to use these side by side. Instead, you may use uv add. This makes sure the package is handled smoothly by uv. For example, let’s install numpy and matplotlib in our newly created project:

uv add matplotlib numpy

This adds the dependencies to the project description in pyproject.toml, resolves any version conflics with other dependencies to generate a new lock file, and installs the new state of the environment in the .venv/ directory. Note that not all dependencies

Converting an existing project from pip (requirements.txt)

If you currently already have a project which uses a requirements.txt together with pip to install packages, these dependencies may be added to uv as well:

uv init
uv add -r requirements.txt

Note that this may cause dependency issues if the requirements are strictly specified. Read the guide for more information.

Using jupyter notebooks

To make sure packages installed in jupyter notebooks end up correctly in project, we have to install a kernel in the virtual environment. Full details may be found in the guide, but it mostly boils down to

uv add --dev ipykernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project

Then jupyter may be started with

uv run --with jupyter jupyter lab

Dependencies may be added preferably from within the notebooks using the !uv add command inside a code cell. It is also possible to add packages using the command line using uv add, however in this case the dependencies are not explicitly specified inside of the notebook, which could cause issues if only the notebook is shared.

Quickly run a notebook without generating a project

In some cases it may be desirable to only quickly execute a notebook, without going through the hassle of having to generate an entire project. For this purpose, uv uses the concept of tools. Tools are python modules that are installed installation-wide, so it does not matter in what directory you are, you will always use the same module. To start a jupyter server as a tool, simply use

uv tool run jupyter lab

This will start a jupyter server where you may execute your code. Note that any installed packages and their versions are not saved this way, so when sharing your project with others this is not recommended.

Using VS Code for Python development

To use the Imphys servers in VS code, the server must first be configured as an ssh client. Follow the steps for logging in to ensure you have a correct ~/.ssh/config file. Then, in VS Code install the Remote Development Extension Pack. Then connect to the servers by opening up the Command Pallette using F1 and choosing the Remote-SSH: Connect to Host option. If your ssh config file is set correctly, this should list all the Imphys servers in the configuration. You can select any of them.

Info

After connecting to the remote server via ssh, all processes inside of vscode are executed on the remote server. Thus, if you lose your connection to the server, you will also not be able to continue your work. VS Code does save the state of the editor when it last had a connection to the remote, so this should not lose any work done.

After connecting, it is recommended to configure a workspace for your project. You can do this using the command (again, press F1 to open the command pallete)

> File: Open Folder

Then, navigate to your project folder.

Configuring your virtual environment for use in VS Code

To use your python environment in VS Code, first ensure the Python Extension is installed. If you want to make use of VS Code jupyter notebook functionality, also install the Jupyter extension. If you have already executed your code using uv at least once, a .venv folder should be present in the project root directory. If not, you can generate one using

uv venv

VSCode should automatically detect the environment and suggest using it as a default project interpreter. If not, in vscode, select Python interpreter using

> Python: Select Interpreter

The correct interpreter should be listed as recommended, with directory ./.venv/bin/python. If you want to use the vscode jupyter functionality, also install a jupyter kernel:

uv add --dev ipykernel
uv add --dev uv

Then, you may install dependencies from the Jupyter notebooks using !uv add.