Skip to content

Commit d221b3d

Browse files
committed
Update README install instructions
1 parent a73c345 commit d221b3d

File tree

1 file changed

+48
-1
lines changed

1 file changed

+48
-1
lines changed

README.rst

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,57 @@ New contributors are welcome!
3030
Installation
3131
------------
3232

33-
::
33+
To install pygame-ce, first make sure you have Python (and pip) installed and available on your PATH.
34+
Then, run the following command in your terminal or command prompt:
35+
36+
.. code-block:: bash
3437
3538
pip install pygame-ce
3639
40+
Note that on some platforms you may need to use ``pip3`` instead of ``pip``.
41+
42+
Linux Note: "Breaking System Packages" Error
43+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44+
45+
On some Linux distributions (like Ubuntu or Debian), installing Python packages with ``pip`` can trigger a message like the following:
46+
47+
.. code-block:: bash
48+
49+
error: externally-managed-environment
50+
This environment is externally managed when system packages are installed.
51+
52+
This means your system Python is managed by the OS, and using ``pip3`` globally might interfere with system packages.
53+
54+
Recommended Workarounds
55+
^^^^^^^^^^^^^^^^^^^^^^^^
56+
57+
1. **Use ``venv`` (virtual environment):**
58+
59+
You can create a virtual environment and install pygame-ce within it.
60+
This way you still use system Python but create a separate environment for installed packages — so they cannot conflict with or break system ones.
61+
62+
.. code-block:: bash
63+
64+
python3 -m venv venv # create a venv named 'venv'
65+
source venv/bin/activate # activate venv
66+
pip install pygame-ce # install packages in venv
67+
68+
2. **Use ``pyenv`` (User-level Python management):**
69+
70+
`pyenv <https://github.com/pyenv/pyenv>`_ lets you install and manage your own Python versions at the user level without touching the system one.
71+
As a plus, you can install and use multiple Python versions side by side.
72+
73+
3. **Use ``uv`` (Fast Modern Package Installer):**
74+
75+
`uv <https://docs.astral.sh/uv/>`_ is a modern, fast Python package and environment manager that can serve as a replacement for both ``venv`` and ``pyenv``.
76+
77+
4. **Use ``--break-system-packages`` (Not Recommended):**
78+
79+
If you absolutely must use the system Python environment, use the ``--break-system-packages`` flag **at your own risk**:
80+
81+
.. code-block:: bash
82+
83+
pip3 install pygame-ce --break-system-packages
3784
3885
Help
3986
----

0 commit comments

Comments
 (0)