Source

distribute / docs / easy_install.txt

The branch 'default' does not exist.
   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
============
Easy Install
============

Easy Install is a python module (``easy_install``) bundled with ``setuptools``
that lets you automatically download, build, install, and manage Python
packages.

Please share your experiences with us! If you encounter difficulty installing
a package, please contact us via the `distutils mailing list
<http://mail.python.org/pipermail/distutils-sig/>`_.  (Note: please DO NOT send
private email directly to the author of setuptools; it will be discarded.  The
mailing list is a searchable archive of previously-asked and answered
questions; you should begin your research there before reporting something as a
bug -- and then do so via list discussion first.)

(Also, if you'd like to learn about how you can use ``setuptools`` to make your
own packages work better with EasyInstall, or provide EasyInstall-like features
without requiring your users to use EasyInstall directly, you'll probably want
to check out the full `setuptools`_ documentation as well.)

.. contents:: **Table of Contents**


Using "Easy Install"
====================


.. _installation instructions:

Installing "Easy Install"
-------------------------

Please see the `setuptools PyPI page <http://pypi.python.org/pypi/setuptools>`_
for download links and basic installation instructions for each of the
supported platforms.

You will need at least Python 2.3.5, or if you are on a 64-bit platform, Python
2.4.  An ``easy_install`` script will be installed in the normal location for
Python scripts on your platform.

Note that the instructions on the setuptools PyPI page assume that you are
are installling to Python's primary ``site-packages`` directory.  If this is
not the case, you should consult the section below on `Custom Installation
Locations`_ before installing.  (And, on Windows, you should not use the
``.exe`` installer when installing to an alternate location.)

Note that ``easy_install`` normally works by downloading files from the
internet.  If you are behind an NTLM-based firewall that prevents Python
programs from accessing the net directly, you may wish to first install and use
the `APS proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such
firewalls in the same way that your web browser(s) do.

(Alternately, if you do not wish easy_install to actually download anything, you
can restrict it from doing so with the ``--allow-hosts`` option; see the
sections on `restricting downloads with --allow-hosts`_ and `command-line
options`_ for more details.)


Troubleshooting
~~~~~~~~~~~~~~~

If EasyInstall/setuptools appears to install correctly, and you can run the
``easy_install`` command but it fails with an ``ImportError``, the most likely
cause is that you installed to a location other than ``site-packages``,
without taking any of the steps described in the `Custom Installation
Locations`_ section below.  Please see that section and follow the steps to
make sure that your custom location will work correctly.  Then re-install.

Similarly, if you can run ``easy_install``, and it appears to be installing
packages, but then you can't import them, the most likely issue is that you
installed EasyInstall correctly but are using it to install packages to a
non-standard location that hasn't been properly prepared.  Again, see the
section on `Custom Installation Locations`_ for more details.


Windows Notes
~~~~~~~~~~~~~

On Windows, an ``easy_install.exe`` launcher will also be installed, so that
you can just type ``easy_install`` as long as it's on your ``PATH``.  If typing
``easy_install`` at the command prompt doesn't work, check to make sure your
``PATH`` includes the appropriate ``C:\\Python2X\\Scripts`` directory.  On
most current versions of Windows, you can change the ``PATH`` by right-clicking
"My Computer", choosing "Properties" and selecting the "Advanced" tab, then
clicking the "Environment Variables" button.  ``PATH`` will be in the "System
Variables" section, and you will need to exit and restart your command shell
(command.com, cmd.exe, bash, or other) for the change to take effect.  Be sure
to add a ``;`` after the last item on ``PATH`` before adding the scripts
directory to it.

Note that instead of changing your ``PATH`` to include the Python scripts
directory, you can also retarget the installation location for scripts so they
go on a directory that's already on the ``PATH``.  For more information see the
sections below on `Command-Line Options`_ and `Configuration Files`_.  You
can pass command line options (such as ``--script-dir``) to
``distribute_setup.py`` to control where ``easy_install.exe`` will be installed.



Downloading and Installing a Package
------------------------------------

For basic use of ``easy_install``, you need only supply the filename or URL of
a source distribution or .egg file (`Python Egg`__).

__ http://peak.telecommunity.com/DevCenter/PythonEggs

**Example 1**. Install a package by name, searching PyPI for the latest
version, and automatically downloading, building, and installing it::

    easy_install SQLObject

**Example 2**. Install or upgrade a package by name and version by finding
links on a given "download page"::

    easy_install -f http://pythonpaste.org/package_index.html SQLObject

**Example 3**. Download a source distribution from a specified URL,
automatically building and installing it::

    easy_install http://example.com/path/to/MyPackage-1.2.3.tgz

**Example 4**. Install an already-downloaded .egg file::

    easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg

**Example 5**.  Upgrade an already-installed package to the latest version
listed on PyPI::

    easy_install --upgrade PyProtocols

**Example 6**.  Install a source distribution that's already downloaded and
extracted in the current directory (New in 0.5a9)::

    easy_install .

**Example 7**.  (New in 0.6a1) Find a source distribution or Subversion
checkout URL for a package, and extract it or check it out to
``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
can be examined or edited.  (The package will not be installed, but it can
easily be installed with ``easy_install ~/projects/sqlobject``.  See `Editing
and Viewing Source Packages`_ below for more info.)::

    easy_install --editable --build-directory ~/projects SQLObject

**Example 7**. (New in 0.6.11) Install a distribution within your home dir::

    easy_install --user SQLAlchemy

Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
"distribution" names), and package+version specifiers.  In each case, it will
attempt to locate the latest available version that meets your criteria.

When downloading or processing downloaded files, Easy Install recognizes
distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
.tar.bz2, or .zip.  And of course it handles already-built .egg
distributions as well as ``.win32.exe`` installers built using distutils.

By default, packages are installed to the running Python installation's
``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
option to specify an alternative directory, or specify an alternate location
using distutils configuration files.  (See `Configuration Files`_, below.)

By default, any scripts included with the package are installed to the running
Python installation's standard script installation location.  However, if you
specify an installation directory via the command line or a config file, then
the default directory for installing scripts will be the same as the package
installation directory, to ensure that the script will have access to the
installed package.  You can override this using the ``-s`` or ``--script-dir``
option.

Installed packages are added to an ``easy-install.pth`` file in the install
directory, so that Python will always use the most-recently-installed version
of the package.  If you would like to be able to select which version to use at
runtime, you should use the ``-m`` or ``--multi-version`` option.


Upgrading a Package
-------------------

You don't need to do anything special to upgrade a package: just install the
new version, either by requesting a specific version, e.g.::

    easy_install "SomePackage==2.0"

a version greater than the one you have now::

    easy_install "SomePackage>2.0"

using the upgrade flag, to find the latest available version on PyPI::

    easy_install --upgrade SomePackage

or by using a download page, direct download URL, or package filename::

    easy_install -f http://example.com/downloads ExamplePackage

    easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg

    easy_install my_downloads/ExamplePackage-2.0.tgz

If you're using ``-m`` or ``--multi-version`` , using the ``require()``
function at runtime automatically selects the newest installed version of a
package that meets your version criteria.  So, installing a newer version is
the only step needed to upgrade such packages.

If you're installing to a directory on PYTHONPATH, or a configured "site"
directory (and not using ``-m``), installing a package automatically replaces
any previous version in the ``easy-install.pth`` file, so that Python will
import the most-recently installed version by default.  So, again, installing
the newer version is the only upgrade step needed.

If you haven't suppressed script installation (using ``--exclude-scripts`` or
``-x``), then the upgraded version's scripts will be installed, and they will
be automatically patched to ``require()`` the corresponding version of the
package, so that you can use them even if they are installed in multi-version
mode.

``easy_install`` never actually deletes packages (unless you're installing a
package with the same name and version number as an existing package), so if
you want to get rid of older versions of a package, please see `Uninstalling
Packages`_, below.


Changing the Active Version
---------------------------

If you've upgraded a package, but need to revert to a previously-installed
version, you can do so like this::

    easy_install PackageName==1.2.3

Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
If a package matching the requested name and version is not already installed
in a directory on ``sys.path``, it will be located via PyPI and installed.

If you'd like to switch to the latest installed version of ``PackageName``, you
can do so like this::

    easy_install PackageName

This will activate the latest installed version.  (Note: if you have set any
``find_links`` via distutils configuration files, those download pages will be
checked for the latest available version of the package, and it will be
downloaded and installed if it is newer than your current version.)

Note that changing the active version of a package will install the newly
active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
specified.


Uninstalling Packages
---------------------

If you have replaced a package with another version, then you can just delete
the package(s) you don't need by deleting the PackageName-versioninfo.egg file
or directory (found in the installation directory).

If you want to delete the currently installed version of a package (or all
versions of a package), you should first run::

    easy_install -m PackageName

This will ensure that Python doesn't continue to search for a package you're
planning to remove. After you've done this, you can safely delete the .egg
files or directories, along with any scripts you wish to remove.


Managing Scripts
----------------

Whenever you install, upgrade, or change versions of a package, EasyInstall
automatically installs the scripts for the selected package version, unless
you tell it not to with ``-x`` or ``--exclude-scripts``.  If any scripts in
the script directory have the same name, they are overwritten.

Thus, you do not normally need to manually delete scripts for older versions of
a package, unless the newer version of the package does not include a script
of the same name.  However, if you are completely uninstalling a package, you
may wish to manually delete its scripts.

EasyInstall's default behavior means that you can normally only run scripts
from one version of a package at a time.  If you want to keep multiple versions
of a script available, however, you can simply use the ``--multi-version`` or
``-m`` option, and rename the scripts that EasyInstall creates.  This works
because EasyInstall installs scripts as short code stubs that ``require()`` the
matching version of the package the script came from, so renaming the script
has no effect on what it executes.

For example, suppose you want to use two versions of the ``rst2html`` tool
provided by the `docutils <http://docutils.sf.net/>`_ package.  You might
first install one version::

    easy_install -m docutils==0.3.9

then rename the ``rst2html.py`` to ``r2h_039``, and install another version::

    easy_install -m docutils==0.3.10

This will create another ``rst2html.py`` script, this one using docutils
version 0.3.10 instead of 0.3.9.  You now have two scripts, each using a
different version of the package.  (Notice that we used ``-m`` for both
installations, so that Python won't lock us out of using anything but the most
recently-installed version of the package.)



Tips & Techniques
-----------------


Multiple Python Versions
~~~~~~~~~~~~~~~~~~~~~~~~

As of version 0.6a11, EasyInstall installs itself under two names:
``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
used to install it.  Thus, if you install EasyInstall for both Python 2.3 and
2.4, you can use the ``easy_install-2.3`` or ``easy_install-2.4`` scripts to
install packages for Python 2.3 or 2.4, respectively.

Also, if you're working with Python version 2.4 or higher, you can run Python
with ``-m easy_install`` to run that particular Python version's
``easy_install`` command.


Restricting Downloads with ``--allow-hosts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
EasyInstall will look for links and downloads on.  ``--allow-hosts=None``
prevents downloading altogether.  You can also use wildcards, for example
to restrict downloading to hosts in your own intranet.  See the section below
on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.

By default, there are no host restrictions in effect, but you can change this
default by editing the appropriate `configuration files`_ and adding:

.. code-block:: ini

    [easy_install]
    allow_hosts = *.myintranet.example.com,*.python.org

The above example would then allow downloads only from hosts in the
``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
command line.


Installing on Un-networked Machines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Just copy the eggs or source packages you need to a directory on the target
machine, then use the ``-f`` or ``--find-links`` option to specify that
directory's location.  For example::

    easy_install -H None -f somedir SomePackage

will attempt to install SomePackage using only eggs and source packages found
in ``somedir`` and disallowing all remote access.  You should of course make
sure you have all of SomePackage's dependencies available in somedir.

If you have another machine of the same operating system and library versions
(or if the packages aren't platform-specific), you can create the directory of
eggs using a command like this::

    easy_install -zmaxd somedir SomePackage

This will tell EasyInstall to put zipped eggs or source packages for
SomePackage and all its dependencies into ``somedir``, without creating any
scripts or .pth files.  You can then copy the contents of ``somedir`` to the
target machine.  (``-z`` means zipped eggs, ``-m`` means multi-version, which
prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
even if they're installed elsewhere on the machine, and ``-d`` indicates the
directory to place the eggs in.)

You can also build the eggs from local development packages that were installed
with the ``setup.py develop`` command, by including the ``-l`` option, e.g.::

    easy_install -zmaxld somedir SomePackage

This will use locally-available source distributions to build the eggs.


Packaging Others' Projects As Eggs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Need to distribute a package that isn't published in egg form?  You can use
EasyInstall to build eggs for a project.  You'll want to use the ``--zip-ok``,
``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
``-N``, respectively).  Use ``-d`` or ``--install-dir`` to specify the location
where you'd like the eggs placed.  By placing them in a directory that is
published to the web, you can then make the eggs available for download, either
in an intranet or to the internet at large.

If someone distributes a package in the form of a single ``.py`` file, you can
wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
So, something like this::

    easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo

will install the package as an egg, and this::

    easy_install -zmaxd. \
        -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo

will create a ``.egg`` file in the current directory.


Creating your own Package Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to local directories and the Python Package Index, EasyInstall can
find download links on most any web page whose URL is given to the ``-f``
(``--find-links``) option.  In the simplest case, you can simply have a web
page with links to eggs or Python source packages, even an automatically
generated directory listing (such as the Apache web server provides).

If you are setting up an intranet site for package downloads, you may want to
configure the target machines to use your download site by default, adding
something like this to their `configuration files`_:

.. code-block:: ini

    [easy_install]
    find_links = http://mypackages.example.com/somedir/
                 http://turbogears.org/download/
                 http://peak.telecommunity.com/dist/

As you can see, you can list multiple URLs separated by whitespace, continuing
on multiple lines if necessary (as long as the subsequent lines are indented.

If you are more ambitious, you can also create an entirely custom package index
or PyPI mirror.  See the ``--index-url`` option under `Command-Line Options`_,
below, and also the section on `Package Index "API"`_.


Password-Protected Sites
------------------------

If a site you want to download from is password-protected using HTTP "Basic"
authentication, you can specify your credentials in the URL, like so::

    http://some_userid:some_password@some.example.com/some_path/

You can do this with both index page URLs and direct download URLs.  As long
as any HTML pages read by easy_install use *relative* links to point to the
downloads, the same user ID and password will be used to do the downloading.


Controlling Build Options
~~~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall respects standard distutils `Configuration Files`_, so you can use
them to configure build options for packages that it installs from source.  For
example, if you are on Windows using the MinGW compiler, you can configure the
default compiler by putting something like this:

.. code-block:: ini

    [build]
    compiler = mingw32

into the appropriate distutils configuration file.  In fact, since this is just
normal distutils configuration, it will affect any builds using that config
file, not just ones done by EasyInstall.  For example, if you add those lines
to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
default compiler for *all* packages you build.  See `Configuration Files`_
below for a list of the standard configuration file locations, and links to
more documentation on using distutils configuration files.


Editing and Viewing Source Packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes a package's source distribution  contains additional documentation,
examples, configuration files, etc., that are not part of its actual code.  If
you want to be able to examine these files, you can use the ``--editable``
option to EasyInstall, and EasyInstall will look for a source distribution
or Subversion URL for the package, then download and extract it or check it out
as a subdirectory of the ``--build-directory`` you specify.  If you then wish
to install the package after editing or configuring it, you can do so by
rerunning EasyInstall with that directory as the target.

Note that using ``--editable`` stops EasyInstall from actually building or
installing the package; it just finds, obtains, and possibly unpacks it for
you.  This allows you to make changes to the package if necessary, and to
either install it in development mode using ``setup.py develop`` (if the
package uses setuptools, that is), or by running ``easy_install projectdir``
(where ``projectdir`` is the subdirectory EasyInstall created for the
downloaded package.

In order to use ``--editable`` (``-e`` for short), you *must* also supply a
``--build-directory`` (``-b`` for short).  The project will be placed in a
subdirectory of the build directory.  The subdirectory will have the same
name as the project itself, but in all-lowercase.  If a file or directory of
that name already exists, EasyInstall will print an error message and exit.

Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
You *must* specify project names (and optional version requirements) so that
EasyInstall knows what directory name(s) to create.  If you need to force
EasyInstall to use a particular URL or filename, you should specify it as a
``--find-links`` item (``-f`` for short), and then also specify
the project name, e.g.::

    easy_install -eb ~/projects \
     -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
     ctypes==0.9.6


Dealing with Installation Conflicts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
people using older versions of EasyInstall can consult it.  As of version
0.6a11, installation conflicts are handled automatically without deleting the
old or system-installed packages, and without ignoring the issue.  Instead,
eggs are automatically shifted to the front of ``sys.path`` using special
code added to the ``easy-install.pth`` file.  So, if you are using version
0.6a11 or better of setuptools, you do not need to worry about conflicts,
and the following issues do not apply to you.)

EasyInstall installs distributions in a "managed" way, such that each
distribution can be independently activated or deactivated on ``sys.path``.
However, packages that were not installed by EasyInstall are "unmanaged",
in that they usually live all in one directory and cannot be independently
activated or deactivated.

As a result, if you are using EasyInstall to upgrade an existing package, or
to install a package with the same name as an existing package, EasyInstall
will warn you of the conflict.  (This is an improvement over ``setup.py
install``, becuase the ``distutils`` just install new packages on top of old
ones, possibly combining two unrelated packages or leaving behind modules that
have been deleted in the newer version of the package.)

By default, EasyInstall will stop the installation if it detects a conflict
between an existing, "unmanaged" package, and a module or package in any of
the distributions you're installing.  It will display a list of all of the
existing files and directories that would need to be deleted for the new
package to be able to function correctly.  You can then either delete these
conflicting files and directories yourself and re-run EasyInstall, or you can
just use the ``--delete-conflicting`` or ``--ignore-conflicts-at-my-risk``
options, as described under `Command-Line Options`_, below.

Of course, once you've replaced all of your existing "unmanaged" packages with
versions managed by EasyInstall, you won't have any more conflicts to worry
about!


Compressed Installation
~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall tries to install packages in zipped form, if it can.  Zipping
packages can improve Python's overall import performance if you're not using
the ``--multi-version`` option, because Python processes zipfile entries on
``sys.path`` much faster than it does directories.

As of version 0.5a9, EasyInstall analyzes packages to determine whether they
can be safely installed as a zipfile, and then acts on its analysis.  (Previous
versions would not install a package as a zipfile unless you used the
``--zip-ok`` option.)

The current analysis approach is fairly conservative; it currenly looks for:

 * Any use of the ``__file__`` or ``__path__`` variables (which should be
   replaced with ``pkg_resources`` API calls)

 * Possible use of ``inspect`` functions that expect to manipulate source files
   (e.g. ``inspect.getsource()``)

 * Top-level modules that might be scripts used with ``python -m`` (Python 2.4)

If any of the above are found in the package being installed, EasyInstall will
assume that the package cannot be safely run from a zipfile, and unzip it to
a directory instead.  You can override this analysis with the ``-zip-ok`` flag,
which will tell EasyInstall to install the package as a zipfile anyway.  Or,
you can use the ``--always-unzip`` flag, in which case EasyInstall will always
unzip, even if its analysis says the package is safe to run as a zipfile.

Normally, however, it is simplest to let EasyInstall handle the determination
of whether to zip or unzip, and only specify overrides when needed to work
around a problem.  If you find you need to override EasyInstall's guesses, you
may want to contact the package author and the EasyInstall maintainers, so that
they can make appropriate changes in future versions.

(Note: If a package uses ``setuptools`` in its setup script, the package author
has the option to declare the package safe or unsafe for zipped usage via the
``zip_safe`` argument to ``setup()``.  If the package author makes such a
declaration, EasyInstall believes the package's author and does not perform its
own analysis.  However, your command-line option, if any, will still override
the package author's choice.)


Reference Manual
================

Configuration Files
-------------------

(New in 0.4a2)

You may specify default options for EasyInstall using the standard
distutils configuration files, under the command heading ``easy_install``.
EasyInstall will look first for a ``setup.cfg`` file in the current directory,
then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
and Windows, respectively), and finally a ``distutils.cfg`` file in the
``distutils`` package directory.  Here's a simple example:

.. code-block:: ini

    [easy_install]

    # set the default location to install packages
    install_dir = /home/me/lib/python

    # Notice that indentation can be used to continue an option
    # value; this is especially useful for the "--find-links"
    # option, which tells easy_install to use download links on
    # these pages before consulting PyPI:
    #
    find_links = http://sqlobject.org/
                 http://peak.telecommunity.com/dist/

In addition to accepting configuration for its own options under
``[easy_install]``, EasyInstall also respects defaults specified for other
distutils commands.  For example, if you don't set an ``install_dir`` for
``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
command, this will become EasyInstall's default installation directory.  Thus,
if you are already using distutils configuration files to set default install
locations, build options, etc., EasyInstall will respect your existing settings
until and unless you override them explicitly in an ``[easy_install]`` section.

For more information, see also the current Python documentation on the `use and
location of distutils configuration files <http://docs.python.org/inst/config-syntax.html>`_.

Notice that ``easy_install`` will use the ``setup.cfg`` from the current
working directory only if it was triggered from ``setup.py`` through the
``install_requires`` option. The standalone command will not use that file.

Command-Line Options
--------------------

``--zip-ok, -z``
    Install all packages as zip files, even if they are marked as unsafe for
    running as a zipfile.  This can be useful when EasyInstall's analysis
    of a non-setuptools package is too conservative, but keep in mind that
    the package may not work correctly.  (Changed in 0.5a9; previously this
    option was required in order for zipped installation to happen at all.)

``--always-unzip, -Z``
    Don't install any packages as zip files, even if the packages are marked
    as safe for running as a zipfile.  This can be useful if a package does
    something unsafe, but not in a way that EasyInstall can easily detect.
    EasyInstall's default analysis is currently very conservative, however, so
    you should only use this option if you've had problems with a particular
    package, and *after* reporting the problem to the package's maintainer and
    to the EasyInstall maintainers.

    (Note: the ``-z/-Z`` options only affect the installation of newly-built
    or downloaded packages that are not already installed in the target
    directory; if you want to convert an existing installed version from
    zipped to unzipped or vice versa, you'll need to delete the existing
    version first, and re-run EasyInstall.)

``--multi-version, -m``
    "Multi-version" mode. Specifying this option prevents ``easy_install`` from
    adding an ``easy-install.pth`` entry for the package being installed, and
    if an entry for any version the package already exists, it will be removed
    upon successful installation. In multi-version mode, no specific version of
    the package is available for importing, unless you use
    ``pkg_resources.require()`` to put it on ``sys.path``. This can be as
    simple as::

        from pkg_resources import require
        require("SomePackage", "OtherPackage", "MyPackage")

    which will put the latest installed version of the specified packages on
    ``sys.path`` for you. (For more advanced uses, like selecting specific
    versions and enabling optional dependencies, see the ``pkg_resources`` API
    doc.)

    Changed in 0.6a10: this option is no longer silently enabled when
    installing to a non-PYTHONPATH, non-"site" directory.  You must always
    explicitly use this option if you want it to be active.

``--upgrade, -U``   (New in 0.5a4)
    By default, EasyInstall only searches online if a project/version
    requirement can't be met by distributions already installed
    on sys.path or the installation directory.  However, if you supply the
    ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
    index and ``--find-links`` URLs before selecting a version to install.  In
    this way, you can force EasyInstall to use the latest available version of
    any package it installs (subject to any version requirements that might
    exclude such later versions).

``--install-dir=DIR, -d DIR``
    Set the installation directory. It is up to you to ensure that this
    directory is on ``sys.path`` at runtime, and to use
    ``pkg_resources.require()`` to enable the installed package(s) that you
    need.

    (New in 0.4a2) If this option is not directly specified on the command line
    or in a distutils configuration file, the distutils default installation
    location is used.  Normally, this would be the ``site-packages`` directory,
    but if you are using distutils configuration files, setting things like
    ``prefix`` or ``install_lib``, then those settings are taken into
    account when computing the default installation directory, as is the
    ``--prefix`` option.

``--script-dir=DIR, -s DIR``
    Set the script installation directory.  If you don't supply this option
    (via the command line or a configuration file), but you *have* supplied
    an ``--install-dir`` (via command line or config file), then this option
    defaults to the same directory, so that the scripts will be able to find
    their associated package installation.  Otherwise, this setting defaults
    to the location where the distutils would normally install scripts, taking
    any distutils configuration file settings into account.

``--exclude-scripts, -x``
    Don't install scripts.  This is useful if you need to install multiple
    versions of a package, but do not want to reset the version that will be
    run by scripts that are already installed.

``--user`` (New in 0.6.11)
    Use the the user-site-packages as specified in :pep:`370`
    instead of the global site-packages.

``--always-copy, -a``   (New in 0.5a4)
    Copy all needed distributions to the installation directory, even if they
    are already present in a directory on sys.path.  In older versions of
    EasyInstall, this was the default behavior, but now you must explicitly
    request it.  By default, EasyInstall will no longer copy such distributions
    from other sys.path directories to the installation directory, unless you
    explicitly gave the distribution's filename on the command line.

    Note that as of 0.6a10, using this option excludes "system" and
    "development" eggs from consideration because they can't be reliably
    copied.  This may cause EasyInstall to choose an older version of a package
    than what you expected, or it may cause downloading and installation of a
    fresh copy of something that's already installed.  You will see warning
    messages for any eggs that EasyInstall skips, before it falls back to an
    older version or attempts to download a fresh copy.

``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
    Scan the specified "download pages" or directories for direct links to eggs
    or other distributions.  Any existing file or directory names or direct
    download URLs are immediately added to EasyInstall's search cache, and any
    indirect URLs (ones that don't point to eggs or other recognized archive
    formats) are added to a list of additional places to search for download
    links.  As soon as EasyInstall has to go online to find a package (either
    because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
    used), the specified URLs will be downloaded and scanned for additional
    direct links.

    Eggs and archives found by way of ``--find-links`` are only downloaded if
    they are needed to meet a requirement specified on the command line; links
    to unneeded packages are ignored.

    If all requested packages can be found using links on the specified
    download pages, the Python Package Index will not be consulted unless you
    also specified the ``--upgrade`` or ``-U`` option.

    (Note: if you want to refer to a local HTML file containing links, you must
    use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
    archive are ignored.)

    You may specify multiple URLs or file/directory names with this option,
    separated by whitespace.  Note that on the command line, you will probably
    have to surround the URL list with quotes, so that it is recognized as a
    single option value.  You can also specify URLs in a configuration file;
    see `Configuration Files`_, above.

    Changed in 0.6a10: previously all URLs and directories passed to this
    option were scanned as early as possible, but from 0.6a10 on, only
    directories and direct archive links are scanned immediately; URLs are not
    retrieved unless a package search was already going to go online due to a
    package not being available locally, or due to the use of the ``--update``
    or ``-U`` option.

``--no-find-links`` Blocks the addition of any link. (New in Distribute 0.6.11)
    This is useful if you want to avoid adding links defined in a project
    easy_install is installing (wether it's a requested project or a
    dependency.). When used, ``--find-links`` is ignored.

``--delete-conflicting, -D`` (Removed in 0.6a11)
    (As of 0.6a11, this option is no longer necessary; please do not use it!)

    If you are replacing a package that was previously installed *without*
    using EasyInstall, the old version may end up on ``sys.path`` before the
    version being installed with EasyInstall.  EasyInstall will normally abort
    the installation of a package if it detects such a conflict, and ask you to
    manually remove the conflicting files or directories.  If you specify this
    option, however, EasyInstall will attempt to delete the files or
    directories itself, and then proceed with the installation.

``--ignore-conflicts-at-my-risk`` (Removed in 0.6a11)
    (As of 0.6a11, this option is no longer necessary; please do not use it!)

    Ignore conflicting packages and proceed with installation anyway, even
    though it means the package probably won't work properly.  If the
    conflicting package is in a directory you can't write to, this may be your
    only option, but you will need to take more invasive measures to get the
    installed package to work, like manually adding it to ``PYTHONPATH`` or to
    ``sys.path`` at runtime.

``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
    Specifies the base URL of the Python Package Index.  The default is
    http://pypi.python.org/simple if not specified.  When a package is requested
    that is not locally available or linked from a ``--find-links`` download
    page, the package index will be searched for download pages for the needed
    package, and those download pages will be searched for links to download
    an egg or source distribution.

``--editable, -e`` (New in 0.6a1)
    Only find and download source distributions for the specified projects,
    unpacking them to subdirectories of the specified ``--build-directory``.
    EasyInstall will not actually build or install the requested projects or
    their dependencies; it will just find and extract them for you.  See
    `Editing and Viewing Source Packages`_ above for more details.

``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
    Set the directory used to build source packages.  If a package is built
    from a source distribution or checkout, it will be extracted to a
    subdirectory of the specified directory.  The subdirectory will have the
    same name as the extracted distribution's project, but in all-lowercase.
    If a file or directory of that name already exists in the given directory,
    a warning will be printed to the console, and the build will take place in
    a temporary directory instead.

    This option is most useful in combination with the ``--editable`` option,
    which forces EasyInstall to *only* find and extract (but not build and
    install) source distributions.  See `Editing and Viewing Source Packages`_,
    above, for more information.

``--verbose, -v, --quiet, -q`` (New in 0.4a4)
    Control the level of detail of EasyInstall's progress messages.  The
    default detail level is "info", which prints information only about
    relatively time-consuming operations like running a setup script, unpacking
    an archive, or retrieving a URL.  Using ``-q`` or ``--quiet`` drops the
    detail level to "warn", which will only display installation reports,
    warnings, and errors.  Using ``-v`` or ``--verbose`` increases the detail
    level to include individual file-level operations, link analysis messages,
    and distutils messages from any setup scripts that get run.  If you include
    the ``-v`` option more than once, the second and subsequent uses are passed
    down to any setup scripts, increasing the verbosity of their reporting as
    well.

``--dry-run, -n`` (New in 0.4a4)
    Don't actually install the package or scripts.  This option is passed down
    to any setup scripts run, so packages should not actually build either.
    This does *not* skip downloading, nor does it skip extracting source
    distributions to a temporary/build directory.

``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
    If you are installing from a source distribution, and are *not* using the
    ``--zip-ok`` option, this option controls the optimization level for
    compiling installed ``.py`` files to ``.pyo`` files.  It does not affect
    the compilation of modules contained in ``.egg`` files, only those in
    ``.egg`` directories.  The optimization level can be set to 0, 1, or 2;
    the default is 0 (unless it's set under ``install`` or ``install_lib`` in
    one of your distutils configuration files).

``--record=FILENAME``  (New in 0.5a4)
    Write a record of all installed files to FILENAME.  This is basically the
    same as the same option for the standard distutils "install" command, and
    is included for compatibility with tools that expect to pass this option
    to "setup.py install".

``--site-dirs=DIRLIST, -S DIRLIST``   (New in 0.6a1)
    Specify one or more custom "site" directories (separated by commas).
    "Site" directories are directories where ``.pth`` files are processed, such
    as the main Python ``site-packages`` directory.  As of 0.6a10, EasyInstall
    automatically detects whether a given directory processes ``.pth`` files
    (or can be made to do so), so you should not normally need to use this
    option.  It is is now only necessary if you want to override EasyInstall's
    judgment and force an installation directory to be treated as if it
    supported ``.pth`` files.

``--no-deps, -N``  (New in 0.6a6)
    Don't install any dependencies.  This is intended as a convenience for
    tools that wrap eggs in a platform-specific packaging system.  (We don't
    recommend that you use it for anything else.)

``--allow-hosts=PATTERNS, -H PATTERNS``   (New in 0.6a6)
    Restrict downloading and spidering to hosts matching the specified glob
    patterns.  E.g. ``-H *.python.org`` restricts web access so that only
    packages listed and downloadable from machines in the ``python.org``
    domain.  The glob patterns must match the *entire* user/host/port section of
    the target URL(s).  For example, ``*.python.org`` will NOT accept a URL
    like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
    Multiple patterns can be specified by separting them with commas.  The
    default pattern is ``*``, which matches anything.

    In general, this option is mainly useful for blocking EasyInstall's web
    access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
    or other trusted site.  EasyInstall will do the best it can to satisfy
    dependencies given your host restrictions, but of course can fail if it
    can't find suitable packages.  EasyInstall displays all blocked URLs, so
    that you can adjust your ``--allow-hosts`` setting if it is more strict
    than you intended.  Some sites may wish to define a restrictive default
    setting for this option in their `configuration files`_, and then manually
    override the setting on the command line as needed.

``--prefix=DIR`` (New in 0.6a10)
    Use the specified directory as a base for computing the default
    installation and script directories.  On Windows, the resulting default
    directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
    while on other platforms the defaults will be
    ``prefix/lib/python2.X/site-packages`` (with the appropriate version
    substituted) for libraries and ``prefix/bin`` for scripts.

    Note that the ``--prefix`` option only sets the *default* installation and
    script directories, and does not override the ones set on the command line
    or in a configuration file.

``--local-snapshots-ok, -l`` (New in 0.6c6)
    Normally, EasyInstall prefers to only install *released* versions of
    projects, not in-development ones, because such projects may not
    have a currently-valid version number.  So, it usually only installs them
    when their ``setup.py`` directory is explicitly passed on the command line.

    However, if this option is used, then any in-development projects that were
    installed using the ``setup.py develop`` command, will be used to build
    eggs, effectively upgrading the "in-development" project to a snapshot
    release.  Normally, this option is used only in conjunction with the
    ``--always-copy`` option to create a distributable snapshot of every egg
    needed to run an application.

    Note that if you use this option, you must make sure that there is a valid
    version number (such as an SVN revision number tag) for any in-development
    projects that may be used, as otherwise EasyInstall may not be able to tell
    what version of the project is "newer" when future installations or
    upgrades are attempted.


.. _non-root installation:

Custom Installation Locations
-----------------------------

By default, EasyInstall installs python packages into Python's main ``site-packages`` directory,
and manages them using a custom ``.pth`` file in that same directory.

Very often though, a user or developer wants ``easy_install`` to install and manage python packages
in an alternative location, usually for one of 3 reasons:

1. They don't have access to write to the main Python site-packages directory.

2. They want a user-specific stash of packages, that is not visible to other users.

3. They want to isolate a set of packages to a specific python application, usually to minimize
   the possibility of version conflicts.

Historically, there have been many approaches to achieve custom installation.
The following section lists only the easiest and most relevant approaches [1]_.

`Use the "--user" option`_

`Use the "--user" option and customize "PYTHONUSERBASE"`_

`Use "virtualenv"`_

.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_ in Python 2.6.

.. _PEP-370: http://www.python.org/dev/peps/pep-0370/


Use the "--user" option
~~~~~~~~~~~~~~~~~~~~~~~
With Python 2.6 came the User scheme for installation, which means that all
python distributions support an alternative install location that is specific to a user [2]_ [3]_.
The Default location for each OS is explained in the python documentation
for the ``site.USER_BASE`` variable.  This mode of installation can be turned on by
specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
This approach serves the need to have a user-specific stash of packages.

.. [2] Prior to Python2.6, Mac OS X offered a form of the User scheme. That is now subsumed into the User scheme introduced in Python 2.6.
.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.

Use the "--user" option and customize "PYTHONUSERBASE"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment
variable, which updates the value of ``site.USER_BASE``.  To isolate packages to a specific
application, simply set the OS environment of that application to a specific value of
``PYTHONUSERBASE``, that contains just those packages.

Use "virtualenv"
~~~~~~~~~~~~~~~~
"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby
creating an isolated location to intall packages.  The evolution of "virtualenv" started before the existence
of the User installation scheme.  "virtualenv" provides a version of ``easy_install`` that is
scoped to the cloned python install and is used in the normal way. "virtualenv" does offer various features
that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages.

Please refer to the `virtualenv`_ documentation for more details.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv



Package Index "API"
-------------------

Custom package indexes (and PyPI) must follow the following rules for
EasyInstall to be able to look up and download packages:

1. Except where stated otherwise, "pages" are HTML or XHTML, and "links"
   refer to ``href`` attributes.

2. Individual project version pages' URLs must be of the form
   ``base/projectname/version``, where ``base`` is the package index's base URL.

3. Omitting the ``/version`` part of a project page's URL (but keeping the
   trailing ``/``) should result in a page that is either:

   a) The single active version of that project, as though the version had been
      explicitly included, OR

   b) A page with links to all of the active version pages for that project.

4. Individual project version pages should contain direct links to downloadable
   distributions where possible.  It is explicitly permitted for a project's
   "long_description" to include URLs, and these should be formatted as HTML
   links by the package index, as EasyInstall does no special processing to
   identify what parts of a page are index-specific and which are part of the
   project's supplied description.

5. Where available, MD5 information should be added to download URLs by
   appending a fragment identifier of the form ``#md5=...``, where ``...`` is
   the 32-character hex MD5 digest.  EasyInstall will verify that the
   downloaded file's MD5 digest matches the given value.

6. Individual project version pages should identify any "homepage" or
   "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
   on the HTML elements linking to those URLs. Use of these attributes will
   cause EasyInstall to always follow the provided links, unless it can be
   determined by inspection that they are downloadable distributions. If the
   links are not to downloadable distributions, they are retrieved, and if they
   are HTML, they are scanned for download links. They are *not* scanned for
   additional "homepage" or "download" links, as these are only processed for
   pages that are part of a package index site.

7. The root URL of the index, if retrieved with a trailing ``/``, must result
   in a page containing links to *all* projects' active version pages.

   (Note: This requirement is a workaround for the absence of case-insensitive
   ``safe_name()`` matching of project names in URL paths. If project names are
   matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
   mechanism), then it is not necessary to include this all-packages listing
   page.)

8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
   automatically use ``index.html`` files, if present, when trying to read a
   directory with a trailing ``/`` on the URL.


Backward Compatibility
~~~~~~~~~~~~~~~~~~~~~~

Package indexes that wish to support setuptools versions prior to 0.6b4 should
also follow these rules:

* Homepage and download links must be preceded with ``"<th>Home Page"`` or
  ``"<th>Download URL"``, in addition to (or instead of) the ``rel=""``
  attributes on the actual links.  These marker strings do not need to be
  visible, or uncommented, however!  For example, the following is a valid
  homepage link that will work with any version of setuptools::

    <li>
     <strong>Home Page:</strong>
     <!-- <th>Home Page -->
     <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a>
    </li>

  Even though the marker string is in an HTML comment, older versions of
  EasyInstall will still "see" it and know that the link that follows is the
  project's home page URL.

* The pages described by paragraph 3(b) of the preceding section *must*
  contain the string ``"Index of Packages</title>"`` somewhere in their text.
  This can be inside of an HTML comment, if desired, and it can be anywhere
  in the page.  (Note: this string MUST NOT appear on normal project pages, as
  described in paragraphs 2 and 3(a)!)

In addition, for compatibility with PyPI versions that do not use ``#md5=``
fragment IDs, EasyInstall uses the following regular expression to match PyPI's
displayed MD5 info (broken onto two lines for readability)::

    <a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5
    &amp;digest=([0-9a-f]{32})">md5</a>\)

History
=======

0.6c9
 * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting
   is flattened out in the resulting egg.  (There was a case-sensitivity
   problem that affected some distributions, notably ``pywin32``.)

 * Prevent ``--help-commands`` and other junk from showing under Python 2.5
   when running ``easy_install --help``.

 * Fixed GUI scripts sometimes not executing on Windows

 * Fixed not picking up dependency links from recursive dependencies.

 * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs

 * Changes for Jython compatibility

 * Improved error message when a requirement is also a directory name, but the
   specified directory is not a source package.

 * Fixed ``--allow-hosts`` option blocking ``file:`` URLs

 * Fixed HTTP SVN detection failing when the page title included a project
   name (e.g. on SourceForge-hosted SVN)

 * Fix Jython script installation to handle ``#!`` lines better when
   ``sys.executable`` is a script.

 * Removed use of deprecated ``md5`` module if ``hashlib`` is available

 * Keep site directories (e.g. ``site-packages``) from being included in
   ``.pth`` files.

0.6c7
 * ``ftp:`` download URLs now work correctly.

 * The default ``--index-url`` is now ``http://pypi.python.org/simple``, to use
   the Python Package Index's new simpler (and faster!) REST API.

0.6c6
 * EasyInstall no longer aborts the installation process if a URL it wants to
   retrieve can't be downloaded, unless the URL is an actual package download.
   Instead, it issues a warning and tries to keep going.

 * Fixed distutils-style scripts originally built on Windows having their line
   endings doubled when installed on any platform.

 * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects
   installed using ``setup.py develop``.

 * Fixed not HTML-decoding URLs scraped from web pages

0.6c5
 * Fixed ``.dll`` files on Cygwin not having executable permisions when an egg
   is installed unzipped.

0.6c4
 * Added support for HTTP "Basic" authentication using ``http://user:pass@host``
   URLs.  If a password-protected page contains links to the same host (and
   protocol), those links will inherit the credentials used to access the
   original page.

 * Removed all special support for Sourceforge mirrors, as Sourceforge's
   mirror system now works well for non-browser downloads.

 * Fixed not recognizing ``win32.exe`` installers that included a custom
   bitmap.

 * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they
   are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as
   is done by ``os.urandom()`` on some platforms).

 * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable``
   has a space in it (e.g., the user installed Python to a ``Program Files``
   directory).

0.6c3
 * You can once again use "python -m easy_install" with Python 2.4 and above.

 * Python 2.5 compatibility fixes added.

0.6c2
 * Windows script wrappers now support quoted arguments and arguments
   containing spaces.  (Patch contributed by Jim Fulton.)

 * The ``ez_setup.py`` script now actually works when you put a setuptools
   ``.egg`` alongside it for bootstrapping an offline machine.

 * A writable installation directory on ``sys.path`` is no longer required to
   download and extract a source distribution using ``--editable``.

 * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable``
   contains non-ASCII characters, to prevent deprecation warnings about an
   unspecified encoding when the script is run.

0.6c1
 * EasyInstall now includes setuptools version information in the
   ``User-Agent`` string sent to websites it visits.

0.6b4
 * Fix creating Python wrappers for non-Python scripts

 * Fix ``ftp://`` directory listing URLs from causing a crash when used in the
   "Home page" or "Download URL" slots on PyPI.

 * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile
   or directory is deleted/overwritten.

 * Fix not recognizing HTML 404 pages from package indexes.

 * Allow ``file://`` URLs to be used as a package index.  URLs that refer to
   directories will use an internally-generated directory listing if there is
   no ``index.html`` file in the directory.

 * Allow external links in a package index to be specified using
   ``rel="homepage"`` or ``rel="download"``, without needing the old
   PyPI-specific visible markup.

 * Suppressed warning message about possibly-misspelled project name, if an egg
   or link for that project name has already been seen.

0.6b3
 * Fix local ``--find-links`` eggs not being copied except with
   ``--always-copy``.

 * Fix sometimes not detecting local packages installed outside of "site"
   directories.

 * Fix mysterious errors during initial ``setuptools`` install, caused by
   ``ez_setup`` trying to run ``easy_install`` twice, due to a code fallthru
   after deleting the egg from which it's running.

0.6b2
 * Don't install or update a ``site.py`` patch when installing to a
   ``PYTHONPATH`` directory with ``--multi-version``, unless an
   ``easy-install.pth`` file is already in use there.

 * Construct ``.pth`` file paths in such a way that installing an egg whose
   name begins with ``import`` doesn't cause a syntax error.

 * Fixed a bogus warning message that wasn't updated since the 0.5 versions.

0.6b1
 * Better ambiguity management: accept ``#egg`` name/version even if processing
   what appears to be a correctly-named distutils file, and ignore ``.egg``
   files with no ``-``, since valid Python ``.egg`` files always have a version
   number (but Scheme eggs often don't).

 * Support ``file://`` links to directories in ``--find-links``, so that
   easy_install can build packages from local source checkouts.

 * Added automatic retry for Sourceforge mirrors.  The new download process is
   to first just try dl.sourceforge.net, then randomly select mirror IPs and
   remove ones that fail, until something works.  The removed IPs stay removed
   for the remainder of the run.

 * Ignore bdist_dumb distributions when looking at download URLs.

0.6a11
 * Process ``dependency_links.txt`` if found in a distribution, by adding the
   URLs to the list for scanning.

 * Use relative paths in ``.pth`` files when eggs are being installed to the
   same directory as the ``.pth`` file.  This maximizes portability of the
   target directory when building applications that contain eggs.

 * Added ``easy_install-N.N`` script(s) for convenience when using multiple
   Python versions.

 * Added automatic handling of installation conflicts.  Eggs are now shifted to
   the front of sys.path, in an order consistent with where they came from,
   making EasyInstall seamlessly co-operate with system package managers.

   The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options
   are now no longer necessary, and will generate warnings at the end of a
   run if you use them.

 * Don't recursively traverse subdirectories given to ``--find-links``.

0.6a10
 * Added exhaustive testing of the install directory, including a spawn test
   for ``.pth`` file support, and directory writability/existence checks.  This
   should virtually eliminate the need to set or configure ``--site-dirs``.

 * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of
   RTFM-ing.  :)

 * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it
   manually to make it work.  ``--multi-version`` is no longer a silent
   default; you must explicitly use it if installing to a non-PYTHONPATH,
   non-"site" directory.

 * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``,
   ``--install-dir``, and ``--script-dir`` options, whether on the command line
   or in configuration files.

 * Improved SourceForge mirror processing to work faster and be less affected
   by transient HTML changes made by SourceForge.

 * PyPI searches now use the exact spelling of requirements specified on the
   command line or in a project's ``install_requires``.  Previously, a
   normalized form of the name was used, which could lead to unnecessary
   full-index searches when a project's name had an underscore (``_``) in it.

 * EasyInstall can now download bare ``.py`` files and wrap them in an egg,
   as long as you include an ``#egg=name-version`` suffix on the URL, or if
   the ``.py`` file is listed as the "Download URL" on the project's PyPI page.
   This allows third parties to "package" trivial Python modules just by
   linking to them (e.g. from within their own PyPI page or download links
   page).

 * The ``--always-copy`` option now skips "system" and "development" eggs since
   they can't be reliably copied.  Note that this may cause EasyInstall to
   choose an older version of a package than what you expected, or it may cause
   downloading and installation of a fresh version of what's already installed.

 * The ``--find-links`` option previously scanned all supplied URLs and
   directories as early as possible, but now only directories and direct
   archive links are scanned immediately.  URLs are not retrieved unless a
   package search was already going to go online due to a package not being
   available locally, or due to the use of the ``--update`` or ``-U`` option.

 * Fixed the annoying ``--help-commands`` wart.

0.6a9
 * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside
   "baskets") when they weren't explicitly listed in the ``.pth`` file.

 * If more than one URL appears to describe the exact same distribution, prefer
   the shortest one.  This helps to avoid "table of contents" CGI URLs like the
   ones on effbot.org.

 * Quote arguments to python.exe (including python's path) to avoid problems
   when Python (or a script) is installed in a directory whose name contains
   spaces on Windows.

 * Support full roundtrip translation of eggs to and from ``bdist_wininst``
   format.  Running ``bdist_wininst`` on a setuptools-based package wraps the
   egg in an .exe that will safely install it as an egg (i.e., with metadata
   and entry-point wrapper scripts), and ``easy_install`` can turn the .exe
   back into an ``.egg`` file or directory and install it as such.

0.6a8
 * Update for changed SourceForge mirror format

 * Fixed not installing dependencies for some packages fetched via Subversion

 * Fixed dependency installation with ``--always-copy`` not using the same
   dependency resolution procedure as other operations.

 * Fixed not fully removing temporary directories on Windows, if a Subversion
   checkout left read-only files behind

 * Fixed some problems building extensions when Pyrex was installed, especially
   with Python 2.4 and/or packages using SWIG.

0.6a7
 * Fixed not being able to install Windows script wrappers using Python 2.3

0.6a6
 * Added support for "traditional" PYTHONPATH-based non-root installation, and
   also the convenient ``virtual-python.py`` script, based on a contribution
   by Ian Bicking.  The setuptools egg now contains a hacked ``site`` module
   that makes the PYTHONPATH-based approach work with .pth files, so that you
   can get the full EasyInstall feature set on such installations.

 * Added ``--no-deps`` and ``--allow-hosts`` options.

 * Improved Windows ``.exe`` script wrappers so that the script can have the
   same name as a module without confusing Python.

 * Changed dependency processing so that it's breadth-first, allowing a
   depender's preferences to override those of a dependee, to prevent conflicts
   when a lower version is acceptable to the dependee, but not the depender.
   Also, ensure that currently installed/selected packages aren't given
   precedence over ones desired by a package being installed, which could
   cause conflict errors.

0.6a3
 * Improved error message when trying to use old ways of running
   ``easy_install``.  Removed the ability to run via ``python -m`` or by
   running ``easy_install.py``; ``easy_install`` is the command to run on all
   supported platforms.

 * Improved wrapper script generation and runtime initialization so that a
   VersionConflict doesn't occur if you later install a competing version of a
   needed package as the default version of that package.

 * Fixed a problem parsing version numbers in ``#egg=`` links.

0.6a2
 * EasyInstall can now install "console_scripts" defined by packages that use
   ``setuptools`` and define appropriate entry points.  On Windows, console
   scripts get an ``.exe`` wrapper so you can just type their name.  On other
   platforms, the scripts are installed without a file extension.

 * Using ``python -m easy_install`` or running ``easy_install.py`` is now
   DEPRECATED, since an ``easy_install`` wrapper is now available on all
   platforms.

0.6a1
 * EasyInstall now does MD5 validation of downloads from PyPI, or from any link
   that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest.

 * EasyInstall now handles symlinks in target directories by removing the link,
   rather than attempting to overwrite the link's destination.  This makes it
   easier to set up an alternate Python "home" directory (as described above in
   the `Non-Root Installation`_ section).

 * Added support for handling MacOS platform information in ``.egg`` filenames,
   based on a contribution by Kevin Dangoor.  You may wish to delete and
   reinstall any eggs whose filename includes "darwin" and "Power_Macintosh",
   because the format for this platform information has changed so that minor
   OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
   previous OS version to become obsolete.

 * easy_install's dependency processing algorithms have changed.  When using
   ``--always-copy``, it now ensures that dependencies are copied too.  When
   not using ``--always-copy``, it tries to use a single resolution loop,
   rather than recursing.

 * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
   extensions.

 * Added ``--site-dirs`` option to allow adding custom "site" directories.
   Made ``easy-install.pth`` work in platform-specific alternate site
   directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X).

 * If you manually delete the current version of a package, the next run of
   EasyInstall against the target directory will now remove the stray entry
   from the ``easy-install.pth`` file.

 * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID
   as pointing to the named project's source checkout.  Such URLs have a lower
   match precedence than any other kind of distribution, so they'll only be
   used if they have a higher version number than any other available
   distribution, or if you use the ``--editable`` option.  The ``#egg``
   fragment can contain a version if it's formatted as ``#egg=proj-ver``,
   where ``proj`` is the project name, and ``ver`` is the version number.  You
   *must* use the format for these values that the ``bdist_egg`` command uses;
   i.e., all non-alphanumeric runs must be condensed to single underscore
   characters.

 * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_
   above for more info.  Also, slightly changed the behavior of the
   ``--build-directory`` option.

 * Fixed the setup script sandbox facility not recognizing certain paths as
   valid on case-insensitive platforms.

0.5a12
 * Fix ``python -m easy_install`` not working due to setuptools being installed
   as a zipfile.  Update safety scanner to check for modules that might be used
   as ``python -m`` scripts.

 * Misc. fixes for win32.exe support, including changes to support Python 2.4's
   changed ``bdist_wininst`` format.

0.5a10
 * Put the ``easy_install`` module back in as a module, as it's needed for
   ``python -m`` to run it!

 * Allow ``--find-links/-f`` to accept local directories or filenames as well
   as URLs.

0.5a9
 * EasyInstall now automatically detects when an "unmanaged" package or
   module is going to be on ``sys.path`` ahead of a package you're installing,
   thereby preventing the newer version from being imported.  By default, it
   will abort installation to alert you of the problem, but there are also
   new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``)
   available to change the default behavior.  (Note: this new feature doesn't
   take effect for egg files that were built with older ``setuptools``
   versions, because they lack the new metadata file required to implement it.)

 * The ``easy_install`` distutils command now uses ``DistutilsError`` as its
   base error type for errors that should just issue a message to stderr and
   exit the program without a traceback.

 * EasyInstall can now be given a path to a directory containing a setup
   script, and it will attempt to build and install the package there.

 * EasyInstall now performs a safety analysis on module contents to determine
   whether a package is likely to run in zipped form, and displays
   information about what modules may be doing introspection that would break
   when running as a zipfile.

 * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that
   would ordinarily be considered safe to unzip, and changed the meaning of
   ``--zip-ok/-z`` to "always leave everything zipped".

0.5a8
 * There is now a separate documentation page for `setuptools`_; revision
   history that's not specific to EasyInstall has been moved to that page.

 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools

0.5a5
 * Made ``easy_install`` a standard ``setuptools`` command, moving it from
   the ``easy_install`` module to ``setuptools.command.easy_install``.  Note
   that if you were importing or extending it, you must now change your imports
   accordingly.  ``easy_install.py`` is still installed as a script, but not as
   a module.

0.5a4
 * Added ``--always-copy/-a`` option to always copy needed packages to the
   installation directory, even if they're already present elsewhere on
   sys.path. (In previous versions, this was the default behavior, but now
   you must request it.)

 * Added ``--upgrade/-U`` option to force checking PyPI for latest available
   version(s) of all packages requested by name and version, even if a matching
   version is available locally.

 * Added automatic installation of dependencies declared by a distribution
   being installed.  These dependencies must be listed in the distribution's
   ``EGG-INFO`` directory, so the distribution has to have declared its
   dependencies by using setuptools.  If a package has requirements it didn't
   declare, you'll still have to deal with them yourself.  (E.g., by asking
   EasyInstall to find and install them.)

 * Added the ``--record`` option to ``easy_install`` for the benefit of tools
   that run ``setup.py install --record=filename`` on behalf of another
   packaging system.)

0.5a3
 * Fixed not setting script permissions to allow execution.

 * Improved sandboxing so that setup scripts that want a temporary directory
   (e.g. pychecker) can still run in the sandbox.

0.5a2
 * Fix stupid stupid refactoring-at-the-last-minute typos.  :(

0.5a1
 * Added support for converting ``.win32.exe`` installers to eggs on the fly.
   EasyInstall will now recognize such files by name and install them.

 * Fixed a problem with picking the "best" version to install (versions were
   being sorted as strings, rather than as parsed values)

0.4a4
 * Added support for the distutils "verbose/quiet" and "dry-run" options, as
   well as the "optimize" flag.

 * Support downloading packages that were uploaded to PyPI (by scanning all
   links on package pages, not just the homepage/download links).

0.4a3
 * Add progress messages to the search/download process so that you can tell
   what URLs it's reading to find download links.  (Hopefully, this will help
   people report out-of-date and broken links to package authors, and to tell
   when they've asked for a package that doesn't exist.)

0.4a2
 * Added support for installing scripts

 * Added support for setting options via distutils configuration files, and
   using distutils' default options as a basis for EasyInstall's defaults.

 * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the
   script installation directory option.

 * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
   Python includes SSL support.

0.4a1
 * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
   and search PyPI for needed packages.

0.3a4
 * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
   URL installs, to avoid running the wrong setup.py.

0.3a3
 * Added ``--build-directory=DIR/-b DIR`` option.

 * Added "installation report" that explains how to use 'require()' when doing
   a multiversion install or alternate installation directory.

 * Added SourceForge mirror auto-select (Contributed by Ian Bicking)

 * Added "sandboxing" that stops a setup script from running if it attempts to
   write to the filesystem outside of the build area

 * Added more workarounds for packages with quirky ``install_data`` hacks

0.3a2
 * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
   automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)

 * Misc. bug fixes

0.3a1
 * Initial release.


Future Plans
============

* Additional utilities to list/remove/verify packages
* Signature checking?  SSL?  Ability to suppress PyPI search?
* Display byte progress meter when downloading distributions and long pages?
* Redirect stdout/stderr to log during run_setup?
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.